Skip to content

contributing-code.md

Latest commit

 

History

History
90 lines (65 loc) · 5.56 KB

contributing-code.md

File metadata and controls

90 lines (65 loc) · 5.56 KB
Raw

Code contributions

Project and code leads are experienced HOT volunteer and staff developers and the main points of contact for the project. They are also the final reviewers of issues and pull requests. Code leads will review pull requests and provide feedback. The purpose of this role is to help contributors, provide consistency and ensure code quality.

All of the Tasking Manager development is going to happen in the project repository and everything we work on shall be related to and documented in issues of the related issue queue.

Code basics

  1. Write tests for all new backend features and use a tool (like coveralls.io) to measure test coverage.
  2. Consider writing tests when building new frontend.
  3. Stick to pep8 python style guide for the backend.
  4. Apply ESLint and prettier style guide rules for the frontend code.
  5. Export translatable strings with make refresh-translatables and include them in your commit.

Code collaboration and version control

Note: We use git flow as our branching model. Read more here and here, and refer to this cheatsheet if you aren’t familiar with it yet. You probably want to install a helper application to facilitate the flow a bit.

  • Use branches in the tasking-manager project. This allows others to rebase your branch when they are reviewing or to continue started work. We follow git flow’s naming convention
    • feature/ISSUENUMBER-SHORT-TITLE-SEPARATED-BY-HYPHENS for general new features you are working on
    • hotfix/ISSUENUMBER-SHORT-TITLE-SEPARATED-BY-HYPHENS for important bug fixes that need to go into the main releases as soon as possible (e.g. for a normal feature feature/893-restrict-available-editors).
  • Make sure your PR is always up to date and rebased with the latest develop branch.
  • Try to build a nice and understandable commit history of the project. Please use meaningful commit messages and try to unite/squash related work into one commit. Eventually we will squash commits before merging a new feature or hotfix into the main branches (develop and master).
  • Give meaningful and understandable testing instructions in your PR. Highlight important preconditions and try to make life easier for the reviewer.

Comments

Sometimes it's not apparent from the code itself what it does, or more importantly, why it does that. Good comments help your fellow developers understand the code better and make sure that it is doing the right thing.

When developing, you should:

  • Comment your code - do not go overboard, but explain the bits which might be difficult to understand. As a general rule of thumb, try to explain what the code does, why it does it, and why it should be the way it is or where it could be improved in the future.
  • Check existing comments to ensure they are not misleading.

Committing

When you submit pull requests, the project maintainer has to read them and understand them. This is difficult enough at the best of times, and misunderstanding pull requests can lead to them being more difficult to merge. To help with this, when making pull requests you should:

  • Split up large changes into smaller units of functionality.
  • Keep your commit messages relevant to the changes in each individual unit.

When writing commit messages please try and stick to the same style as other commits, namely:

  • A one line summary, starting with a capital letter.
  • A blank line.
  • Full description, as proper sentences.

For simple commits the one line summary is often enough and the body of the commit message can be left out.

Before sending a PR, make sure you run the following commands and include the changes in your commit.

  • Code formatting:
    • Format all backend code by running Black: black manage.py backend tests migrations
    • Format all frontend code with prettier either by configuring your editor or by running yarn prettier inside the frontend directory.
  • Coding standards: Make sure you adhere to the coding standards eventually risen by Flake8: flake8 manage.py backend tests migrations
  • Prepare for translations: In case you have introduced new strings on the frontend, the translation source file must be updated this can be done via make refresh-translatables or yarn build-locales (inside the frontend directory).

If you have forked this project on GitHub then the best way to submit your patches is to push your changes back to your GitHub repository and then send a "pull request" via GitHub to the main repository.

You can use this git pre-commit hook to format both the frontend and the backend code:

#!/bin/sh
JS_FILES=$(git diff --cached --name-only --diff-filter=ACMR "*.js" "*.jsx" | sed 's| |\\ |g')
PY_FILES=$(git diff --cached --name-only --diff-filter=ACMR "*.py" | sed 's| |\\ |g')
([ -z "$JS_FILES" ] && [ -z "$PY_FILES" ]) && exit 0

# Prettify all selected files
echo "$JS_FILES" | xargs ./frontend/node_modules/.bin/prettier --write
echo "$PY_FILES" | xargs black

# Add back the modified/prettified files to staging
echo "$JS_FILES" | xargs git add
echo "$PY_FILES" | xargs git add

exit 0