Skip to main content

Contributing guidelines

With so many projects and repositories, it may quickly become overwhelming and daunting to contribute. Most of our codebase is hosted on GitHub (or GitLab for internal projects). The de-facto solution to push code onto these version control systems is called Git.

There are already numerous tutorials for basic Git workflows and actions, such as:

  • git pull
  • git push
  • git add
  • git commit
  • git merge

Do familiarize yourself with these commands, especially the last command git merge and the various use-cases of it.

GUI Git

You may be tempted to use GitHub Desktop initially to handle all your Git workflows. In general, it is highly recommended to learn the CLI version instead, as it provides much more in-depth functionality that will be covered below. However, GitHub Desktop is acceptable for most basic usage of pushing and pulling code.

Advanced git usage​

Some advanced git commands that you will find useful in your day-to-day coding. Do look up tutorials on these workflows if you want to use them.

  • git stash
    • Stashing your changes is a useful and effective way to stash your commits away and switch branches, before switching back to your development branch and resuming where you left off.
    • git stash to quickly stash your commits (you may need to specify -u to include untracked files in your stash)
    • git stash list to view all your different git stashes
    • git stash pop to take your latest git stash and apply those changes
    • git stash apply to take your latest git stash and apply those changes, but without losing the stash from your list of stashes
  • git rebase vs git merge
    • There is a long-running debate on whether rebasing or merging is superior. In general, ACUBE prefers to squash and rebase commits, as we find that it keeps the commit history "clean" while still keeping the context of the merge.
  • git switch vs git checkout
  • git rebase and git amend

Deploying your code​

In general, there are 2 methods that ACUBE uses to maintain code.

  1. Deploy a staging environment from a staging branch, and only merge the staging branch into main once it is tested on the staging environment.
    • Sandbox uses this code deployment flow.
    • Each new development branch will be forked from the staging branch and merged into the staging branch when ready.
  2. Deploy both staging from main, and only deploy on production for new releases.
    • ACUBETotal uses this code deployment flow.
    • The main branch contains all the code. Code is forked from the main branch and merged back into the main branch, from which the staging environment will be deployed.
    • As and when (based on either timely updates or critical bug fixes), new releases will be made, from which the production environment is deployed.

We also use project tracking software such as Jira to keep track of all work done and future backlog. As a general guideline, all code should be merged via a pull request for easy tracking.

tip

Review your own pull request after creating your own, before asking others to review your PR. Treat this as you are reviewing someone else's PR and be as critical as possible. This will help to quicken the review process when asking others to merge it into the main branch.

Git commit guidelines​

It is good practice to split your commits into sizable chunks, i.e. each commit should only do 1 task. We enforce the use of semantic commit messages as well. Commit messages should also be in the imperative present tense. Here are some examples of semantic commit messages:

  • feat: add searching of elasticsearch results
  • build: add support for rar files
  • deps: update next.js to 13.5
  • ui: add animations in notification toasts
  • fix: remove incompatible fields from elasticsearch indexing

Examples of bad commit messages:

  • ui: improve submissions page
    • Too generic, requires more specific information about the changes made
  • Added fix for capa microservice
    • Lacking the main type of commit (in this context, fix)
    • Use of past tense
    • What exactly are you fixing in the capa microservice?

As a general rule of thumb, others should be able to easily see what that commit did from the message.

tip

When working on your development branch, it can be extremely tedious to write semantic commit messages for all your changes, especially if you're committing for the end of the day. Instead, you should name your commits as you see fit, and simply rename your commits when making a pull request via rebasing/cherry-picking.

The whole point of keeping the git commit history clean is to hold each engineer accountable for his/her code. This is especially useful when debugging/future development work so that we have the context of who is responsible for which portion of the code and who is the corresponding subject matter expert via the git blame.

It is also useful to look at the commit messages, as they may provide insight into why the code is designed a certain way.

As such, it is also good practice to avoid making unnecessary changes in your commits (e.g. adding unnecessary empty lines/spaces, unnecessary renaming of variables, etc.).