Skip to content

Commit

Permalink
update contribution guidelines
Browse files Browse the repository at this point in the history
  • Loading branch information
JannisNe committed Sep 22, 2022
1 parent 8d9a584 commit 0ca72d0
Showing 1 changed file with 41 additions and 4 deletions.
45 changes: 41 additions & 4 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,47 @@ If you are a member of the IceCube collaboration, you can also ask for permissio

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 [![Build Status](https://travis-ci.org/icecube/flarestack.svg?branch=master)](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 new branch, implement your changes and when you're done, request review by the current maintainers
(you can find who that is in the documentation). This ensures that the people in charge know what's going on and can
keep an overview over the changes.

* *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 [![Coverage Status](https://coveralls.io/repos/github/icecube/flarestack/badge.svg?branch=master)](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).
### 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
[![CI](https://github.com/icecube/flarestack/actions/workflows/continous_integration.yml/badge.svg)](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.

* *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).
### 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
[![Coverage Status](https://coveralls.io/repos/github/icecube/flarestack/badge.svg?branch=master)](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).

0 comments on commit 0ca72d0

Please sign in to comment.