Contributing to the Web App

Conventions

The app follows the PEP 8 style guide, which is the one that Python officially endorse. pylint itself checks for compliance with PEP 8, so running pylint over your code can check for any style differences. If you use Sublime as your text editor, SublimeLinter is a neat plugin that highlights any style issues in your code. Then, you can install the PEP 8 plugin for SublimeLinter.

Avoid tracking data files--add them to .gitignore. 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 the asterisk):

* <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. This Makefile has two main 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.

Because of its sandboxed nature, Travis CI needs to build and install all dependencies every build, which can take several minutes. Ideally, you would run make all locally before pushing a commit to the remote to avoid this wait.

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.

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 work once your feature is merged.

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

Creating a Release and Versioning

When the code is ready to be released to stakeholders, navigate to the releases page and use the "Draft a new release" button. The major release number should always be v1. (v2 is explicitly reserved for versions of Malasakit that include an audio interface, such support for feature phones.) Check with the maintainers on the minor release number. Releases that add minor fixes to an existing release should use an incrementing patch number (for instance, v1.25.1, v1.25.2, etc. for patches to v1.25). Releases that are stable but 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.