search

unicef / magicbox

A platform that uses real-time data to inform life-saving humanitarian responses to emergency situations
https://www.unicef.org/innovation/Magicbox
BSD 3-Clause "New" or "Revised" License
86 stars 16 forks source link

Write about CI & Code health checks in the Docs #39

Closed thoat closed 6 years ago

thoat commented 6 years ago

As suggested by @jwflory here, I started a draft to fill in two sections in the GitHub Workflow article for our ReadTheDocs:

This is still a work in progress but @jwflory and everyone feels free to jump in if you find certain sentences too complicated to read or some procedures just plain wrong.

I hope to finish this either by the end of this week (Jul 9-13) or early next week (Jul 16-20).

jwflory commented 6 years ago

@thoat The content looks good to me – if you want me to review the final content, let me know and I'm happy to do so. :slightly_smiling_face:

One note that I realized I forgot to put in the contributing guidelines: when writing sentences in the docs, it's convenient to write each sentence on a new line. This is awkward to write, but when it comes to reviewing changes to the docs, it makes reviewing the diff in a pull request really easy. I would recommend putting each sentence on a new line.

thoat commented 6 years ago

You're absolutely right re: the line-by-line writing, @jwflory. (y) I start getting dizzy looking at the clumps of text haha. Thanks so much for the heads-up.

jwflory commented 6 years ago

@thoat Yup, no problem. To be fair, it's not a widely-practiced convention, but I think it's more practical – it makes reading diffs so much easier.

Also, this could be a good thing to make note of in the contributing guidelines for the docs. :slightly_smiling_face:

jwflory commented 6 years ago

Since #40 was merged, it introduces some merge conflicts with this PR. I recommend rebasing this branch against the current master branch of the repository. Rebasing is a convenient way of pulling in new changes to a project since you added work, apply them to the project, and then try to put your changes back on top of the git history.

I recommend reading this blog post or checking out the Open edX lesson on rebasing if you haven't done it before. These were both really helpful for me. :slightly_smiling_face:

thoat commented 6 years ago

Thank you for the heads-up @jwflory ! And thank you for pointing out the direction and resources!

thoat commented 6 years ago

At this moment, I think there should be a new section on how to set up testing framework for a new repository. It involves more design/planning decision going into it, which is beyond the scope of this PR. Hence I have added a new sub-section to the docs via commit 3b9d69f, and thereby completing the sub-section on CodeClimate.

You can view my local run of the docs here.