Git Workflow and Code Style

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

If you are confident that your Python file has 0 style errors according to pylint, add the file address to LINT_TARGETS in the Makefile.

Git Conventions

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

Branching Workflow

Our branching practices will be based off of this guide. The basic idea can be summarized through this image:

In summary:

• The master branch contains code that is production-ready--i.e. we can push the code onto the prod server with confidence that it is tested and bug-free
• We do not have a release branch
• The dev branch contains the "state with the latest delivered development changes for the next release."
  • Any merges or pull requests onto master can only come from the dev branch.
• We have multiple feature branches, which can be merged with each other and with dev.

To merge branch A into branch B, do the following:

$ git checkout B
$ git pull origin B
$ git checkout A
$ git merge --no-ff B
{fix conflicts}
$ git push origin A

To create a new feature branch on the repository off of dev, do the following:

$ git checkout -b {feature_branch_name} dev
$ git push origin {feature_branch_name}

Setting Up Your Git Environment

Whenever you do a new clone of our repository into a folder {repo_root}, perform the following:

$ cd {repo_root}
$ git checkout {working_branch}
$ git config user.name “{your_name}”
$ git config user.email “{your_email_associated_with_github}”
$ git config core.editor “{your_favorite_text_editor}”

The 3rd and 4th step ensure that your code is attributed to you and not somebody else

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 app/{app_name}/test*.py

When you feel like a Python file passes all of PyLint's tests, add it to the space-separated LINT_TARGETS list in the Makefile.

Right now, we have no tests, but that will change in the future.

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 to the Dev Branch

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 with dev.

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

$ git pull origin dev

in your dev 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 dev 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 dev with your feature and keeps the dev branch clean. Optionally, delete the feature branch you were working on, to avoid clutter.

Ideally, each feature 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 dev is always working.

Once we have hit a milestone, Justin will merge the dev branch with the master branch and deploy the changes on the prod server.