Guidelines for Contributing

Conventions

Malasakit follows the Google Python Style Guide, which requries running the pylint linter over source code. pylint itself checks for compliance with PEP 8, a widely-used style guide for Python.

Avoid tracking data files (for example, *.json, *.sqlite3). 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.)

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> is the name of a feature you want to implement. If you run

$ git branch

you should see a list of branches on your local machine, as well as what branch you are currently on (indicated by an asterisk), like so:

* <branch-name>
  master

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 with what changes others have pushed. Note that if two or more developers are editing the same code concurrently, you may have a merge conflict, which git will ask you to resolve when pulling. Follow GitHub's guide on resolving local merge conflicts.

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. This continuous integration service creates a sandboxed environment, clones the repository you just pushed, installs the necessary dependencies, and runs the all target in a top-level Makefile. The all target runs two other targets:

• lint: uses pylint with the pylint_django plugin to evaluate your code's style
• test: runs unit tests in malasakit-django/pcari/test*.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. To avoid waiting several minutes for the build to complete, you may want to run make locally to see if your code will pass.

You can suppress some warnings from pylint using an inline comment that reads pylint: disable=<warning-name>. However, such comments should be used judiciously.

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 and will prompt you to fix any merge conflicts.

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 review your code (two or more for large or critical features). Make any necessary changes, or discuss.

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 adds a single commit on master with your feature and keeps the master branch clean. Prune any stale development branches.

Ideally, each development branch implements one atomic (self-contained) feature--this makes reviewing a pull request easy, and allows others to receive updates often. master should always be in a working (production-ready) state.

Creating a Release and Versioning

When the code is ready to be released, use the "Draft a new release" button on the releases page. Release numbering should follow semantic versioning.

• Increment the major release number for every set of backwards-incompatible changes.
• Increment the minor release number for backwards-compatible features.
• Increment the patch number for backwards-compatible patches.
• Pre-releases that require additional testing should have -beta appended to the tag.

When a release is created, it will create .zip and .tar.gz files with the code on master at the time the release was created. This creates an archive of past versions of Malasakit.