Skip to main content

Native Code Contributing Guide

danger

This document is WIP and is likely to change

Code Reviewing​

All code changes being contributed to the project need to be reviewed by peers before they are added to the project codebase. This helps ensure that the code is of high quality and meets project requirements.

To have your contributions reviewed, you must submit a Merge Request (MR). If you're not familiar with MRs, you can read more about them in the Gitlab documentation.

For a general overview of how we conduct code reviews across the Technology Department, you can read the Developer Code Reviews decision document. This document applies to all projects.

The information in this code contribution guideline is specific to the Native Apps project and supplements the Developer Code Reviews document.

Code Review Tips​

Here are some additional tips to help you have the best possible experience reviewing and having your code reviewed:

  • Focus on reviewing the code, not the person writing it. Be kind and constructive in your feedback.
  • It is always harder to read code, than it is to write it. Write code that is easy to read and understand for humans, not just machines.
  • Ask plenty of questions before passing judgment. The writer's intentions may not be immediately obvious, and asking questions can help clarify any confusion.
  • Set aside time each day for reviewing MRs. Reviewing code is everyone's responsibility, and doing it regularly can help ensure that the project stays on track.
  • When leaving comments on MRs, consider following the Conventional Comments guidelines to ensure clear and effective communication.

Code Commits​

We adhere to the Conventional Commits specification when creating code commits.

This is to ensure that:

  • The git history is easy to traverse.
  • Each commit can be easily understood for the type of change, scope of the change, and summary of changes just from reading the commit message.
  • CI tooling can be used to automate the creation of changelogs/release notes, to be added to releases.

Whilst working on a branch, locally, you are free to create however many WIP commits you feel the need to, with whatever formatting you want for the commit message.

However once you are ready to create a new Merge Request to get your code reviewed and merged with the rest of the codebase, your commit messages will need to adhere to a the Conventional Commits spec, and more specifically to our own config file based on it.

Note: It is fine to have more than one commit, what matters is that each commit is meaningful and describes a specific chunk of your work. Hypothetically, if you were to have implemented a feature that required creating a new API file, a component to consume that API, and the associated tests, your commits could look like:

feat(new-feature): implemented API for the fancy new feature
feat(new-feature): created components to consume API and display response
test(new-feature): wrote tests for fancy feature API and components

Linting Commits​

The formatting rules come from @commitlint/config-conventional which implements the aforementioned Conventional Commits spec.

  • The formatting rules can be extended or modified inside of the commitlint.config.js file at the root of the project.

Once you create a Merge Request, your branch's commit messages will be linted on the merge request CI pipeline by using the commitlint library, during the lint stage of the pipeline.

  • The commit linting check is run on every push to a new branch or merge request, with the explicit exception of the master branch as it historically contains a lot of old commits that will never pass this check.

Here's some examples of valid commits, based on our commit lint rules.

  • feat(group-mode): add emoji support
  • chore: correct typing in race card context
  • fix(smg): incorrect odds shown

Writing conventional commits using commitizen​

Commitizen is a CLI utility that allows you to format your commit messages, according to our own commitlint config file, commitlint.config.js.

It allows you to interactively choose from existing preset commit types and scopes in the config file without having to remember them and type them in manually.

To use it, simply type git-cz or cz in your terminal, after you've staged whatever files you want to commit.

Writing conventional commits using @commitlint/prompt-cli​

If you'd rather use something else, there is commitlint's own prompt-cli tool.

To use it, type yarn commit in your terminal, after you've staged whatever files you want to commit.

It doesn't offer the ability to interactively pick from types and scopes, but it presents you with a schema for the commit and lets you fill out each section step by step. You will see in your terminal a pro-forma of the commit, and then you manually fill out each section one step at a time. However, it doesn't tell you what the enforced options (if any) are there (e.g. the commit types aren't shown like they are for commitizen).

Updating the React Native app's submodule references​

When you merge new code to the android or ios repositories, it does not automatically flow through to the React Native app's main branch.

As they are connected as git submodules, their reference/hash needs to be updated in the RN repository for that to happen.

To do this, the process is as follows:

  • Native engineer merges some work to the android or ios repo's main branch (will use ios as an example below)
  • Native engineer wants that merged work to be updated in RN's main so that the updated iOS code will be included in the next main app builds, and will also get pulled when other engineers run git submodule update on main
  • Open the RN repository root directory in terminal
  • git checkout main
  • git pull
  • then create a branch as you normally would when doing feature work, e.g. git checkout -b feat/update-some-cool-ios-thing
  • on your new branch, run:
  • cd ios-rebuild
  • git checkout main
  • git pull
  • cd ../
  • git add ios-rebuild
  • commit that staged change with a message like chore(native): update ios native submodule
  • create a merge request from your branch to main and get it reviewed and merged

Once merged, RN's main will now have that latest work from iOS's main included in it.

For more info on this process, check out the git submodule documenation: https://git-scm.com/book/en/v2/Git-Tools-Submodules