Skip to content

Contributing

Jump to bottom
Rob Kelly edited this page Apr 23, 2019 · 29 revisions

Contributing to pyGSTi

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.

Contents

Workflow

Minor Patches

Documentation

Conventions

Workflow

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.

Setting Up a Development Environment

pyGSTi developers may use whatever operating system they choose, but out of convenience, this guide will use example commands for Linux and OS X platforms.

If you don't have python 3.7, pip, and git installed, install them using your OS's package manager.

You'll need to have python 3.7 installed. Check your python version and ensure you're using at least 3.7:

$ python3 -V
Python 3.7.2

pyGSTi developers use git to collaborate on development. If you haven't used git before, you may want to take a moment to learn about git -- or at the very least, go through first-time git setup.

You may also want to take a moment to configure your editor or IDE.

Clone the pyGSTi Repository

To be able to contribute code, you need to clone the pyGSTi repository:

$ git clone https://github.com/pyGSTio/pyGSTi.git

pyGSTi uses the unstable develop branch for active development. Switch to it now:

$ cd pyGSTi/
$ git checkout develop

From develop, you should switch to a topic branch for your work. Name it something descriptive, starting with feature- or bugfix- if you're working on a new feature or a bugfix, respectively:

$ git checkout -b feature-my-feature

This branch will only exist locally on your machine until you push it to the remote repository, so don't worry about making changes that could mess up other developers' work.

Install Development Dependencies

You'll most likely want to create and activate a python virtual environment to manage pyGSTi and its dependencies:

$ python3 -m venv local/3.7
$ source local/3.7/bin/activate

(The exact command to activate a virtual environment may vary depending on your shell)

pyGSTi has a number of optional dependencies. In order to run all tests, developers should install pyGSTi with all optional dependencies with pip:

$ pip install -e .[complete]

Write Your Code

Now you can get down to business and add/edit code. Since you're on your own branch, you're free to write whatever you want, but if you're planning on submitting your change back for inclusion in pyGSTi, keep a few things in mind:

  • Code pythonically!
  • Document what you write, and update documentation for everything affected by your contribution.
  • Try to follow our style conventions.
  • Include tests that fail without your code, and pass with it.

Running Tests

TODO

Commit Your Changes

TODO

Update Your Branch

TODO

Submit a Pull Request

TODO

Get some Feedback

TODO

Minor Patches

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

Documentation

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 label: docs label in the issue tracker.

Code & API Documentation

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.

User Guides, Examples, & Tutorials

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.

Developer Wiki

(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.

Publications

TODO

Conventions

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.

Repository

The pyGSTi repository uses 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 develop when creating topic branches
    • Topic branches for bugfixes should have names starting with bugfix-
    • Topic branches for features & enhancements should likewise start with feature-
  • When merging back into develop, developers make a pull request which should be reviewed by another developer.

Style

TODO

Code Style

pyGSTi follows the PEP8 style guide, with a few notable exceptions:

Code Error description Reason for ignoring
E265 block comment should start with '# ' autopep8 will not fix instances of commented-out code
E266 too many leading '#' for block comment Useful for indicating commented-out code
E402 module level import not at top of file Used for a few workarounds to python 2-3 compatibility
E701 multiple statements on one line (colon) More readable for scientific programming
E702 multiple statements on one line (semicolon) ''
E704 multiple statements on one line (def) ''
E722 do not use bare except, specify exception instead Mostly harmless
E741 do not use variables named 'l', 'O', or 'I' Mostly harmless
W503 line break before binary operator Mutually exclusive with W504 (after binary operator)
W605 invalid escape sequence 'x' Used in LaTeX samples
F401 module imported but unused Major namespace refactor planned, TBD
F403 'from module import *' used; unable to detect undefined names ''
F405 name may be undefined, or defined from star imports: module ''

Docstring Style

pyGSTi uses the numpydoc docstring style convention.

Useful Tools

pyGSTi includes configuration for flake8 and editorconfig, which can be used by your editor to highlight errors and automatically apply basic formatting on save. We recommend all pyGSTi contributors take 5 minutes to configure their editors to use the included configurations.

If you use one of the following editors, there are a few packages or plugins that you may want to install to use the configurations we supply:

Testing

TODO

Navigation

Clone this wiki locally