Contribution Guidelines

Git

Some Git Rules

• Branch out from master.

• Perform work in a branch prefixed with one of the following:

Branch prefix	Description
feat/*	A new feature
fix/*	A bug fix
test/*	Adding missing tests
chore/*	Build process or auxiliary tool changes
docs/*	Documentation only changes
refactor/*	A code change that neither fixes a bug or adds a feature
style/*	Markup, white-space, formatting, missing semi-colons etc.
ci/*	CI related changes
perf/*	A code change that improves performance

Why:

Because this way all work is done in isolation on a dedicated branch rather than the main branch. It allows you to submit multiple pull requests without confusion. You can iterate without polluting the master branch with potentially unstable, unfinished code. We use specific branch prefixes so it's easy to discern the type of pull request when scanning the history.

• Append the Clickup task ID to the branch name. EG: feat/super-cool-feature_CU-70px0a

  Why:

  So we have bidirectional context (Clickup <-> Github) without any manual labour.

• Never push into master branch. Make a Pull Request. *The master branch is locked so you shouldn't be able to push to master in any case.

  Why:

  It notifies team members that they have completed a feature. It also enables easy peer-review of the code and dedicates forum for discussing the proposed feature.

• Update your local branch by frequently merging master into your branch.

  Why:

  This ensures that you always have the latest changes and prevents bigger merge conflicts especially on bigger chunks of work

• Resolve potential conflicts while merging and before making a Pull Request.

• Delete local and remote feature branches after merging.

  Why:

  It will clutter up your list of branches with dead branches. It ensures you only ever merge the branch back into (master) once. Feature branches should only exist while the work is still in progress.

• Before making a Pull Request, make sure your feature branch builds successfully and passes all tests (including code style checks).

  Why:

  You are about to add your code to a stable branch. If your feature-branch tests fail, there is a high chance that your destination branch build will fail too. Additionally, you need to apply code style check before making a Pull Request. It aids readability and reduces the chance of formatting fixes being mingled in with actual changes.

Git Workflow

Because of most of the reasons above, we use Feature-branch-workflow.

• Checkout to a new branch

  git checkout -b <branchname>

• Make Changes.

  git add <file1> <file2> ...
  git commit

  Why:

  git add <file1> <file2> ... - you should add only files that make up a small and coherent change.

  git commit will start an editor which lets you separate the subject from the body.

  Tip:

  You could use git add -p instead, which will give you chance to review all of the introduced changes one by one, and decide whether to include them in the commit or not.

• Sync with remote to get changes you’ve missed.

  git checkout master
  git pull

  Why:

  This will give you a chance to deal with conflicts on your machine while merging (later) rather than creating a Pull Request that contains conflicts.

• Update your feature branch with latest changes from master by merging.

  git checkout <branchname>
  git merge master

• If you don’t have conflicts, skip this step. If you have conflicts, resolve them and commit the merge.

  git add .
  git commit -m "Merge master into <branchname>"

• Make a Pull Request.

• Pull request will be accepted, merged and close by a reviewer.

• Remove your local feature branch if you're done.

  git branch -d <branchname>

  to remove all branches which are no longer on remote

  git fetch -p && for branch in `git branch -vv --no-color | grep ': gone]' | awk '{print $1}'`; do git branch -D $branch; done

Github Actions

We have two Github Actions workflows.

• Test: Runs all unit tests
• Firebase: Builds and deploys to a unique staging URL. This can be shared with the team for QA.

Firebase deployments

This workflow only runs on pull requests that are ready for review. It is re-run whenever a new commit is pushed to the pull requests. For this reason it is recommended that you leave your pull requests in draft state while working and only mark as ready for review when you're ready for the staging link to be built.

If you'd like to prevent the firebase staging link from building you can append [skip-firebase] in the pull request title.

Git Commit Guidelines

We have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history.

The commit message formatting can be added using a typical git workflow or through the use of a CLI wizard (Commitizen). To use the wizard, run yarn commit in your terminal after staging your changes in git.

Commit Message Format

Each commit message consists of a header, a body and a footer.

<subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

The subject is mandatory and the body and footer are optional.

Any line of the commit message cannot be longer than 100 characters! This allows the message to be easier to read on GitHub as well as in various git tools.

Revert

If the commit reverts a previous commit, it should begin with revert: , followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

Subject

The subject contains succinct description of the change.

• use the imperative, present tense: "change" not "changed" nor "changes"
• don't capitalize first letter
• no dot (.) at the end

See below for more info on writing good commit messages.

Writing good commit messages

Having a good guideline for creating commits and sticking to it makes working with Git and collaborating with others a lot easier.

• Separate the subject from the body with a newline between the two.

  Why:

  Git is smart enough to distinguish the first line of your commit message as your summary. In fact, if you try git shortlog, instead of git log, you will see a long list of commit messages, consisting of the id of the commit, and the summary only.

• Limit the subject line to 50 characters and Wrap the body at 72 characters.

  why

  Commits should be as fine-grained and focused as possible, it is not the place to be verbose. read more...

• Use imperative mood in the subject line.

  Why:

  Rather than writing messages that say what a committer has done. It's better to consider these messages as the instructions for what is going to be done after the commit is applied on the repository. read more...

• Use the body to explain what and why as opposed to how.

Pull Request Requirements

We squash merge our pull requests into the master branch and the PR title is used as the commit. We use this commit messages to tag releases, generate the change log and deploy so the following PR title formats are required.

Branch prefix	Description
feat: ...	A new feature
fix: ...	A bug fix
test: ...	Adding missing tests
chore: ...	Build process or auxiliary tool changes
docs: ...	Documentation only changes
refactor: ...	A code change that neither fixes a bug or adds a feature
style: ...	Markup, white-space, formatting, missing semi-colons etc.
ci: ...	CI related changes
perf: ...	A code change that improves performance

Code style

We use prettier to auto format our code so that there is always a consistent style. Don't worry about manually formatting code, there are better things to do with your time. Install the prettier plugin in your editor of choice and set it to auto format on save. We also auto format code on the git commit hook to ensure that no strange formatting makes it's way into the code base.