Guidelines for Contributing

Conventions

We follow the Google Python Style Guide, which calls for running the pylint linter over source code. pylint itself checks for compliance with PEP 8, a style guide for standard Python code.

Avoid tracking data files. The reason for this policy is to avoid very noisy diffs, which can occur even if the change is minor. (For instance, updating a single entry in a very long one-line JSON dump.)

From here on, we will assume a basic knowledge of git.

Developing a New Feature

Unlike other projects, there is no need to fork this repository so long as you have write access. To maintain high code quality, all development is done in branches off of the master branch. Commits are never pushed directly to master. To being contributing, create a branch:

$ git checkout -b <branch-name>

where <branch-name> can be your own name, the name of a feature, or some combination of the two. Then, after committing, you can push to the remote server like so:

$ git push origin <branch-name>

For branches multiple developers are working on, use

$ git pull origin <branch-name>

to bring your local copy up-to-date. To see a list of local branches, use

$ git branch

To switch to an existing branch, use

$ git checkout <branch-name>

This will update all of your tracked files to the latest code available in your local <branch-name>.

Build Process

Every time you push to the remote (that is, the GitHub repository), Travis CI will automatically build your code. That is, this continuous integration service creates a sandboxed environment, clones the repository you just pushed, installs the necessary dependencies, and runs a Makefile. This Makefile has two targets:

• lint: uses pylint with the pylint_django plugin to evaluate your code's style
• test: runs unit tests in malasakit-django/pcari/tests.py

To pass the build, all commands in both targets must return nonzero exit codes. As of this writing, this means that the linter must score the code a 10.00/10, and all of the unit tests pass. You can view the log of a build on the Travis CI page for this repository.

You can suppress some warnings from pylint using an inline comment that reads pylint: disable=<warning-name>. However, such comments should be used judiciously. An artificially high number of disabled warnings will be noticed by code reviewers.

You can view the build status of the master branch in the README.md.

Submitting a Feature

Once you wish to submit a feature, go to the pull request age and click the green "New pull request" button to start a new pull request.

Note that in order to be able to merge a branch into master, you must have the latest code from master, which you can obtain by running

$ git pull origin master

in your development branch. This ensures your branch is up-to-date.

When creating a pull request, please summarize the changes you have made, add any relevant labels, reference any relevant issues that the changes address, and assign at least one person to be a code reviewer (two or more for large or critical features). Make any necessary changes requested by the reviewer(s).

Merging into master is blocked until at least one reviewer has approved the pull request and the Travis build passes. Once the criteria for merging are met, use the "squash and merge" option instead of "create merge commit." This keeps the master branch clean and free of many small commits. Optionally, delete the development branch you were working on, to avoid clutter.

Ideally, each development branch implements one atomic (self-contained) feature--this makes reviewing a pull request easy, and allows others to receive your changes often without having to pull from another development branch.

Because of our procedure for checking pull requests, you can be assured that code in master is always working.