We welcome all contributions! Please head to issues to either file any bugs/feature requests or find a task you want to assist with. Make sure to assign yourself the task if you decide to work on it.
See the Github docs for how to make a copy (a fork) of a repository to your own Github account.
Then, clone the repository to your local machine so you can begin making changes.
Add this repository as an upstream remote on your local git repository so that you are able to fetch the latest commits.
On your local machine make sure you have the latest version of the develop
branch:
git checkout develop
git pull upstream develop
This will install all the dependencies of the package including the active branch of challengeutils
.
pip install -r requirements-dev.txt
- Pull the latest content from the
develop
branch of this central repository (not your fork). - Create a feature branch which off the
develop
branch. If there is a GitHub issue that you are addressing, name the branch after the issue with some more detail (likeissue-123-add-some-new-feature
). - After completing work and testing locally (see below), push to your fork.
- In Github, create a pull request from the feature branch of your fork to the
develop
branch of the central repository.
A code maintainer must review and accept your pull request. A code review (which happens with both the contributor and the reviewer present) is required for contributing. This can be performed remotely (e.g., Skype, Hangout, or other video or phone conference).
This package uses semantic versioning for releasing new versions. The version should be updated on the develop
branch as changes are reviewed and merged in by a code maintainer. The version for the package is maintained in the challengeutils/version.py file. A github release should also occur every time develop
is pushed into main
and it should match the version for the package.
Please add tests for new code. These might include unit tests (to test specific functionality of code that was added to support fixing the bug or feature), integration tests (to test that the feature is usable - e.g., it should have complete the expected behavior as reported in the feature request or bug report), or both.
This package uses pytest
to run tests. The test code is located in the test subdirectory.
Here's how to run the test suite:
pytest -vs tests/
Tests are also run automatically by Github Actions on any pull request and are required to pass before merging.
challengeutils
uses Google style Python docstrings. All functions you add must abide by these standards. The Documentation of each python module can be found in docs/python
folder and are auto generated by sphinx
. If you are adding a new module, you must add to a .rst
file into this folder. If you are adding or modifying a command line client function, you must add/modify the files in docs/client
.
To build documentation:
cd docs
make html
open _build/html/index.html
- Always merge all new features into
develop
branch first (unless it is a documentation, readme, or github action patch intomain
) - After initial features are ready in the
develop
branch, create arelease-X.X
branch to prepare for the release.- update
challengeutils/__version__.py
- update
docs/conf.py
version variable - update
docs/about/changelog.md
with release information
- update
- Merge
release-X.X
branch intomain
- Check documentation build for docs: https://sage-bionetworks.github.io/challengeutils/
- Create release tag (
v...
) and include release notes. Also include any known bugs for each release here.