Contributing¶
Where to Start?¶
Want to help but you’re not sure where to start?
Check our issues for help wanted
or good first issue
labels.
Nothing there? Examples and documentation are always a great place to start! If you’re confused about something, chances are a lot of other people are too. If you can offer a clearer way of explaining something or an example that highlights what you were trying to figure out, that’s a great way to contribute!
Development Workflow¶
All development should start and end with the development
branch.
We create all releases from the master
branch,
but no human should ever touch that branch.
If you forget, don’t worry!
master
should never be far behind development
so you probably won’t have any conflicts if you start from master
and our army of bots will make sure that your pull requests end up in the right place. :)
Development Environment¶
All of our checks and tests can be run locally using tox
.
Just pipx install tox
or pip install --user -r ci-requirements.txt
to get set up.
Once you have tox
installed,
check out the config file
for information on the various test environments.
For more information on tox
,
see the tox docs.
Submitting Changes¶
When you’re ready to submit your changes,
open up a pull request against the development
branch.
Operations¶
Ok, so that’s cool and all, but how does all of that work???
We use a variety of GitHub Apps and Action workflows to manage this repo:
Repo Management¶
- settings : We use probot settings to manage most repository settings.
- branch-switcher : We use probot branch switcher to make sure that all pull requests end up with the correct target.
- apply-pr-labels Some of our automation relies on labels being applied to pull requests. This workflow takes care of applying those labels.
- promote
Every time a pull request is merged into
development
, this workflow automatically creates a pull request promoting those changes tomaster
. If a pull request already exists, it will simply be updated as you would expect. - automerge Our branch protection rules define our requirements for a pull request to be accepted. If those requirements are met, this workflow merges those changes.
- publish Libraries are not terribly useful if they are not published to the appropriate package indexes. This workflow takes any published GitHub releases, packages them, and publishes them to PyPI.
Pull Requests and Testing¶
- static-analysis : We check all pull requests with a variety of static analysis tools to ensure the safety, consistency, and quality of our codebase. This also means that computers (not humans!) will complain if you don’t have formatting/etc quite right. :)
- local-tests : We run our local (unit and functional) tests on every pull request.
- integration-tests :
Because they require credentials that are difficult to share,
we only run our integration tests on promotion pull requests from
development
tomaster
. If you want to run these tests for yourself locally, though, you can! Like all of our other tests, our integration tests are all managed throughtox
.