-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
update contribution guidelines (#201)
* update contribution guidelines * update review guideline * include that also for minor changes a PR should be submitted * Update CONTRIBUTING.md Proofreading / minor modifications. * Clarify reproducibility recommendations. Co-authored-by: Massimiliano Lincetto <m.lincetto@gmail.com>
- Loading branch information
Showing
1 changed file
with
55 additions
and
6 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,15 +1,64 @@ | ||
| # Contributing to _flarestack_ | ||
|
|
||
| Since _flarestack_ is an open-source software project, *anyone* can contribute it. You simply need to create a fork of the repository, commit your changes, and then make a pull request. | ||
| Since _flarestack_ is a free and open-source software project, *anyone* can contribute it. You simply need to create a fork of the repository, commit your changes, and then make a pull request. | ||
|
|
||
| If you are a member of the IceCube collaboration, you can also ask for permission to commit changes directly to the master branch. | ||
| If you are a member of the IceCube collaboration, you can also ask for permission to merge directly to the master branch. | ||
|
|
||
| In either case, we have a few general guidelines that are helpful for keeping things organised: | ||
|
|
||
| * *Use Github Issues* to coordinate your development. Whether you found a bug, you want to request an enhancement, or you're actively developing a new feature, Github Issues is a great place to keep everyone informed about what you're working on. Click on the label button to provide more info about your topic. Every time you make a relevant commit, remember to tag the issue (e.g `git commit -m 'progress on #12'`), and when you finish and issue you can close it with a commit too! (e.g `git commit -m 'Close #12`') | ||
| ### 1. Use Github Issues | ||
| Whether you found a bug, you want to request an enhancement, or you're actively developing a new feature, | ||
| Github Issues is a great place to keep everyone informed about what you're working on. | ||
| Click on the label button to provide more info about your topic. | ||
| Every time you make a relevant commit, remember to tag the issue (e.g `git commit -m 'progress on #12'`), | ||
| and when you finish and issue you can close it with a commit too! (e.g `git commit -m 'Close #12`') | ||
|
|
||
| * *Keep Travis Happy!* Travis CI runs all pf our unit tests, to make sure you didn't break anything with your commit. You can see if travis is happy by checking on the github page (look for the badge [](https://travis-ci.org/icecube/flarestack), or a tick/cross next to your commit), or on the travis website https://travis-ci.org/icecube/flarestack. If your commit failed, be sure to check the TravisCI website logs, to see exactly what wen't wrong. If you have access to the Icecube slack, you will see Travis posting directly in the #flarestack channel after each commit. | ||
| ### 2. Use Pull Requests | ||
| After you checked GitHub Issues and found that no one else is working on your idea, be the hero and do so yourself! Create a branch to track your development and submit a PR when it is ready. | ||
|
|
||
| * *Keep Travis Busy!* Travis CI will only run unit tests if we make the unit tests first. When you add a new feature, you also need to add some unit tests so that we can ensure this feature continues to work in the future. Your tests should be saved in the `tests/` directory, and you can find plenty of examples there to copy. Coveralls.io checks how much of the code is covered by tests, and helps you see which lines still need to be covered. You can see all of this on the website: https://coveralls.io/repos/github/icecube/flarestack or a summary badge [](https://coveralls.io/github/icecube/flarestack?branch=master). If your commit adds a lot of new code but does not add unit tests, your commit will be tagged on github with a red cross to let you know that the code coverage is decreasing. If you want to know more about how to design unit tests, you can check out a guide [here](https://medium.com/swlh/introduction-to-unit-testing-in-python-using-unittest-framework-6faa06cc3ee1). | ||
| #### Major contribution | ||
| Create a new branch and implement your changes and when you're done, | ||
| request review by the current maintainers (you can find who they are in the documentation). | ||
| This ensures that the people in charge know what's going on and can keep an overview over the changes. | ||
| You can expect reviewers to give an answer within about a week. Do not hesitate to contact them if there is no reaction | ||
| within that time. | ||
|
|
||
| * *Keep your analysis reproducible!* If you are a member of the Icecube collaboration that is ready for an analysis unblinding, you should create a release of the flarestack software beforehand and include it in your analysis wiki. This ensures that, in the future, anyone can reproduce your analysis exactly by downloading the same version of your siftware. You should also create a readme.md/readme.txt file in your analysis directory, listing the software you used, including all catalogues, and giving some brief instructions for how another person would reproduce your results. An example can be found [here](https://github.com/icecube/flarestack/blob/master/flarestack/analyses/tde/README.txt). | ||
| #### Minor changes | ||
| If you want to only make minor changes, you should also create a branch and submit a pull request. | ||
| But if your changes are minimal and do not touch core functionality (and you have the GitHub access rights), | ||
| you can also merge your pull request directly. | ||
| If in doubt please do take the detour through the review route! | ||
|
|
||
| ### 3. Keep the CI happy! | ||
| GitHub Actions runs all of our unit tests (also for non-master branches), to make sure you didn't break anything with your commit. | ||
| You can see if travis is happy by checking on the GitHub page | ||
| (look for the badge | ||
| [](https://github.com/icecube/flarestack/actions/workflows/continous_integration.yml), | ||
| or a tick/cross next to your commit), or on the [GitHub actions website](https://github.com/icecube/flarestack/actions). | ||
| If your commit failed, be sure to check the logs, to see exactly what went wrong. | ||
| If you have access to the IceCube Slack, | ||
| you will see Travis posting directly in the #flarestack channel after each commit. | ||
|
|
||
| ### 4. Keep the CI busy! | ||
| The CI will only run unit tests if we make the unit tests first. | ||
| When you add a new feature, you also need to add some unit tests so that we can ensure this feature continues to work | ||
| in the future. Your tests should be saved in the `tests/` directory, and you can find plenty of examples there to copy. | ||
| Coveralls.io checks how much of the code is covered by tests, and helps you see which lines still need to be covered. | ||
| You can see all of this on the [website](https://coveralls.io/repos/github/icecube/flarestack) or a summary badge | ||
| [](https://coveralls.io/github/icecube/flarestack?branch=master). | ||
| If your commit adds a lot of new code but does not add unit tests, your commit will be tagged on github with a | ||
| red cross to let you know that the code coverage is decreasing. | ||
| If you want to know more about how to design unit tests, you can check out a guide | ||
| [here](https://medium.com/swlh/introduction-to-unit-testing-in-python-using-unittest-framework-6faa06cc3ee1). | ||
|
|
||
| ### 5. Keep your analysis reproducible! | ||
| If you are a member of the IceCube Collaboration that is ready for an analysis unblinding, | ||
| you should create a release of the flarestack software beforehand and include it in your analysis wiki. | ||
| This ensures that, in the future, anyone can reproduce your analysis exactly by downloading the same version of | ||
| your software. | ||
| You should also create a `readme.md`/`readme.txt` file in your analysis directory, | ||
| listing the software you used, including all catalogues, | ||
| and giving some brief instructions for how another person would reproduce your results. | ||
| An example can be found [here](https://github.com/icecube/flarestack/blob/master/flarestack/analyses/tde/README.txt). | ||
| In general, be sure to follow the most up-to-date reproducibility guidelines of the Collaboration. | ||
| While it has been done in the past, storage of data such as catalogues in the flarestack repository is not currently recommended. |