Contributing
The pyGSTi project uses a simple & flexible branching git workflow. Members of the pyGSTio group should use this document as a guide to making contributions to the pyGSTi codebase.
These guidelines do not apply to contributors outside of the pyGSTio group. If you're an external contributor to pyGSTi, please refer to the general contributor guidelines.
- Setting Up a Development Environment
- Clone the pyGSTi Repository
- Install Development Dependencies
- Write Your Code
- Running Tests
- Commit Your Changes
- Update Your Branch
- Submit a Pull Request
- Get some Feedback
This section is a step-by-step guide to contributing code to the pyGSTi project. You don't need to follow these steps to make a contribution to pyGSTi, but if you're not sure how to use the guidelines and conventions of the project, you might want to check the relevant heading in this section.
TODO
TODO
TODO
TODO
TODO
TODO
TODO
TODO
TODO
For small changes to the pyGSTi codebase, internal contributors are
free to push their commits directly to develop
instead of making a pull request for
review. The purpose of code reviews and pull requests is to make sure
that another pyGSTi developer is aware of what you're adding to the
codebase, so as a rule-of-thumb: if someone would want to know about
what you're adding, make a pull request!
Here are a few examples of changes that probably don't need a PR:
- Renaming local symbols
- Fixing a typo
- Adding or editing a docstring with minor information
Likewise, here are a couple of changes that would definitely need a PR:
- Refactoring something in a module or class namespace
- Adding or removing a feature
- Fixing a bug
- Making extensive changes to documentation across many units
- Adding a missing test case or fixing a broken test
We rely on our contributors to keep our documentation correct, constistent, usable, and up-to-date. If you have additions or corrections to add to our project's documentation, we have a couple of resources available to you.
Issues relating to documentation should be tagged with the
When possible, pull requests that add features should include the documentation for those features, and any revisions to a documented unit should revise documentation accordingly.
If a function, class, or module has an outdated docstring, please fix
it and push the revised documentation directly to
develop. The only exceptions to this are patches
adding or fixing docstrings for a large number of units, which should
be accompanied by a pull request -- use your judgement.
Docstrings in pyGSTi will be parsed to compile the project's documentation on Read the Docs. When adding or editing docstrings, pay close attention to our docstring style conventions.
pyGSTi ships with a number of interactive tutorials and examples in
the form of Jupyter notebooks found in the
jupyter_notebooks directory.
Developers are not expected to add tutorials or examples when adding features, but may do so if they wish.
(YOU ARE HERE)
The project developer wiki is a repository of general information about pyGSTi. It's sort of a catch-all for documentation not covered anywhere else.
When adding new wiki pages or editing existing documentation, let other developers know by creating a new issue in the issue tracker and assigning yourself.
If you are creating a new major section for the wiki, you should manually add it to the navigation menu.
TODO
This section details a few of the common development conventions followed by pyGSTi developers. These are not absolute requirements for contributing, but in some rare cases, contributions to the codebase may be temporarily rejected for breaking from conventions. We really appreciate contributors making an effort to follow these conventions and keep our codebase clean, clear, and maintainable.
The pyGSTi repository has three mainline branches:
-
master-- the stable release branch -
beta-- the unstable pre-release branch -
develop-- the unstable development branch
Developers merge their contributions into
develop. When changes are pushed to develop,
CI will lint the branch for syntax errors and run
unit tests on the development python version (3.7). If
this CI build succeeds, the changes will be automatically pushed to
beta. When the pyGSTi core developers make a new
release, they will manually merge it from beta into
master and push a new tag.
pyGSTi developers use a typical branching workflow. To learn more, the git book has a relevant section. But the gist of it is this:
- Developers branch off of
developwhen creating topic branches- Topic branches for bugfixes should have names starting with
bugfix- - Topic branches for features & enhancements should likewise start
with
feature-
- Topic branches for bugfixes should have names starting with
- When merging back into
develop, developers make a pull request which should be reviewed by another developer.
TODO
TODO
TODO
TODO
TODO