Skip to content

Latest commit

 

History

History
197 lines (153 loc) · 7.3 KB

CONTRIBUTING.md

File metadata and controls

197 lines (153 loc) · 7.3 KB
Raw

Welcome

We're so glad you're thinking about contributing to this open source project! If you're unsure or afraid of anything, just ask or submit the issue or pull request anyway. The worst that can happen is that you'll be politely asked to change something. We appreciate any sort of contribution, and don't want a wall of rules to get in the way of that.

Before contributing, we encourage you to read our CONTRIBUTING policy (you are here), our LICENSE, and our README, all of which should be in this repository.

Issues

If you want to report a bug or request a new feature, the most direct method is to create an issue in this repository. We recommend that you first search through existing issues (both open and closed) to check if your particular issue has already been reported. If it has then you might want to add a comment to the existing issue. If it hasn't then feel free to create a new one.

Pull requests

If you choose to submit a pull request, you will notice that our continuous integration (CI) system runs a fairly extensive set of linters and syntax checkers. Your pull request may fail these checks, and that's OK. If you want you can stop there and wait for us to make the necessary corrections to ensure your code passes the CI checks.

If you want to make the changes yourself, or if you want to become a regular contributor, then you will want to set up pre-commit on your local machine. Once you do that, the CI checks will run locally before you even write your commit message. This speeds up your development cycle considerably.

Setting up pre-commit

There are a few ways to do this, but we prefer to use pyenv and pyenv-virtualenv to create and manage a Python virtual environment specific to this project.

We recommend using the setup-env script located in this repository, as it automates the entire environment configuration process. The dependencies required to run this script are GNU getopt, pyenv, and pyenv-virtualenv. If these tools are already configured on your system, you can simply run the following command:

./setup-env

Otherwise, follow the steps below to manually configure your environment.

Installing and using GNU getopt, pyenv, and pyenv-virtualenv

On macOS, we recommend installing brew. Then installation is as simple as brew install gnu-getopt pyenv pyenv-virtualenv and adding this to your profile:

# GNU getopt must be explicitly added to the path since it is
# keg-only (https://docs.brew.sh/FAQ#what-does-keg-only-mean)
export PATH="$(brew --prefix)/opt/gnu-getopt/bin:$PATH"

# Setup pyenv
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

For Linux, Windows Subsystem for Linux (WSL), or macOS (if you don't want to use brew) you can use pyenv/pyenv-installer to install the necessary tools. Before running this ensure that you have installed the prerequisites for your platform according to the pyenv wiki page. GNU getopt is included in most Linux distributions as part of the util-linux package.

On WSL you should treat your platform as whatever Linux distribution you've chosen to install.

Once you have installed pyenv you will need to add the following lines to your .bash_profile (or .profile):

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init --path)"

and then add the following lines to your .bashrc:

eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

If you want more information about setting up pyenv once installed, please run

pyenv init

and

pyenv virtualenv-init

for the current configuration instructions.

If you are using a shell other than bash you should follow the instructions that the pyenv-installer script outputs.

You will need to reload your shell for these changes to take effect so you can begin to use pyenv.

For a list of Python versions that are already installed and ready to use with pyenv, use the command pyenv versions. To see a list of the Python versions available to be installed and used with pyenv use the command pyenv install --list. You can read more here about the many things that pyenv can do. See here for the additional capabilities that pyenv-virtualenv adds to the pyenv command.

Creating the Python virtual environment

Once pyenv and pyenv-virtualenv are installed on your system, you can create and configure the Python virtual environment with these commands:

cd development-guide
pyenv virtualenv <python_version_to_use> development-guide
pyenv local development-guide
pip install --requirement requirements-dev.txt

Installing the pre-commit hook

Now setting up pre-commit is as simple as:

pre-commit install

At this point the pre-commit checks will run against any files that you attempt to commit. If you want to run the checks against the entire repo, just execute pre-commit run --all-files.

Quality assurance and code reviews

In order to maintain standardization of practices, ensure security standards are being met, and to incorporate third party code as seamlessly as possible, all submitted code will go through our quality assurance (QA) team.

Code contributors are able to coordinate with the QA team at any point during the contribution process. We recommend initiating the discussions as early as possible, to decrease the likelihood of issues around merging or using the contributed code occurring late in the process. However, the QA team is not responsible for the success of the project or for ensuring that all team members follow the development standards which have been established. Any discussions or initial inputs are a courtesy evaluation, and contributing teams remain responsible for the quality of their code, internal coordination, and alignment with the standards set forth in this guide.

The type of contribution being made (e.g. typo corrections vs. a new repository), complexity of code change (e.g. adding a new test vs. adding a new function), and the testability of the code (e.g. well-documented and replicable) will factor into the level of interaction needed with the QA team.

Public domain

This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.

All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.