There are many ways to contribute to Girder, with varying levels of effort. Do try to look through the documentation first if something is unclear, and let us know how we can do better.
- Ask a question on the Girder users email list
- Ask a question in the Discourse Forum
- Submit a feature request or bug, or add to the discussion on the Girder issue tracker
- Submit a Pull Request to improve Girder or its documentation
We encourage a range of contributions, from patches that include passing tests and documentation, all the way down to half-baked ideas that launch discussions.
If you are new to Girder development and you don't have push access to the Girder repository, here are the steps:
- Fork and clone the repository.
- Create a branch.
- Push the branch to your GitHub fork.
- Create a Pull Request.
This corresponds to the Fork & Pull Model mentioned in the GitHub flow guides.
If you have push access to Girder repository, you could simply push your branch into the main repository and create a Pull Request. This corresponds to the Shared Repository Model and will facilitate other developers to checkout your topic without having to configure a remote. It will also simplify the workflow when you are co-developing a branch.
When submitting a PR, make sure to add a Cc: @girder/developers comment to notify Girder developers of your awesome contributions. Based on the comments posted by the reviewers, you may have to revisit your patches.
When you submit a PR to the Girder repo, CircleCI will run the build and test suite on the head of the branch. If you add new commits onto the branch, those will also automatically be run through the CI process. The status of the CI process (passing, failing, or in progress) will be displayed directly in the PR page in GitHub.
The CircleCI build will run according to the circle.yml file, which is useful as an example for how to set up your own environment for testing.
Your test results will be posted on Girder's CircleCI dashboard. These results will list any failed tests. Coverage reports and any screenshots from failed web client tests will be attached to the build as artifact files. You can reach your build by clicking the build status link on your GitHub PR.
Adding new public symbols to Girder's python library should only be done intentionally, as doing so increases the surface of the API and introduces a maintenance burden. Public symbols are packages, modules, and symbols within those modules that do not start with an underscore character. To help with this goal, public symbol addition and removal is tracked automatically as part of our CI process, with the full list of symbols residing in scripts/publicNames.txt
Any PR that adds new public symbols must regenerate the scripts/publicNames.txt file. This is done by running the following script:
python scripts/publicNames.py > scripts/publicNames.txtChanges to the file should be committed as a part of the PR or not all CI tests will pass.
Getting your contributions integrated is relatively straightforward, here is the checklist:
- All tests pass
- Public symbols list is updated in
scripts/publicNames.txt - Any significant changes are added to the
CHANGELOG.rstwith human-readable and understandable text (i.e. not a commit message). Text should be placed in the "Unreleased" section, and grouped into the appropriate sub-section of:- Bug fixes
- Security fixes
- Added features
- Changes
- Deprecations
- Removals
- Consensus is reached. This requires that a reviewer adds an "approved" review via GitHub with no changes requested, and a reasonable amount of time passed without anyone objecting.
Next, there are two scenarios:
- You do NOT have push access: A Girder core developer will integrate your PR.
- You have push access: Simply click on the "Merge pull request" button.
Then, click on the "Delete branch" button that appears afterward.