Skip to main content

Codebase Contribution Standards

Pre-Requisites​

This guide assumes you've installed and/or configured the following tools on your local machine:

  • Git
  • GitHub
  • SSH

Please refer to the development environment setup tutorials before you continue.

General Standards​

  • Branching

    • Create branches off main/develop using the format:
      • feature/<short-description>
      • improvement/<short-description>
      • bugfix/<short-description>
      • hotfix/<short-description>
      • patch/<short-description>
    • If unmerged features are needed (dependency on other PRs), create a branch from them instead of the main dev branch.

  • Commits

    • Write clear, concise commit messages in the past tense (e.g., Added authentication middleware, not Add or Adding).
    • Keep commits small and focused — one logical change per commit.
    • Never commit to the main development branch.
    • Any history rewrite will require a force-push. Make sure no one else is working on the same branch first.

  • Pull Requests (PRs)

    • Open a PR as soon as your feature is functional (even if still WIP).
    • PR title should summarize the change.
    • Provide a short description and link any related issues.
    • Draft PRs may also include a ToDo list in their description.
    • If a feature is dependent on another PR that is not yet merged, it should be opened as a Draft and provide a link to the dependency PR in its description.
    • At least two reviewers (or the senior manager) must approve before merging.
    • If a review is not an approval (e.g. request for changes or comments), the reviewer must convert the PR to a draft until the issues are resolved. They should be approved by the original reviewer.
    • All comments need to be resolved prior to merging.

  • Code Quality

    • Ensure PHPCSF, PHPStan, ESLint, TypeScript checks and any other static analysis tools pass their checks before pushing.
    • Run security scans (php-security-checker, npm audit) before opening a PR.
    • Add or update automated tests if applicable.

  • Merging

    • Squash commits before merging unless history is needed.
    • Never merge directly to main/develop.
    • Prefer local management of merge conflicts instead of GitHub's editor. This is due to its limitations.
    • Branches created from other than the main development branch (due to dependency on unmerged features) need to be rebased before merge.
    • Before rebase, it's a good idea to backup the known-working state of your branch by pushing first, and then try to rebase locally.

Common Workflows (FAQs)​

  • How do I resolve merge conflicts?

    • Locally, checkout and pull the development branch, then checkout your own branch.
    • Merge the development branch into your own and resolve any conflicts.
    • Add the resolved files to stage, commit once done with all of them.
    • To cleanup your branch and only keep your own commits, run git rebase <dev-branch>, then run git rebase --continue whenever prompted to do so.
    • Make sure your feature still functions correctly, then run git push --force to rewrite your changes to remote.

  • What happens if an automated test fails on my PR?

    • Fix the issue locally, force-push changes, and wait for the checks to pass before requesting review.

  • What if I accidentally commit to main/develop?

    • Reset your branch and open a PR from a new feature branch.

  • How do I correct my last commit without creating another one?

    • You can make changes locally, add to stage, run git commit --amend and then force-push.
    • Otherwise, you can do git reset --soft HEAD~1 to undo your last commit and keep files in stage, make changes then commit again.

  • How do I test a small change in my feature branch without breaking it?

    • Push the latest known working commit to remote, then test changes locally.

  • How do I copy a specific file from a commit?

    • You can use git cherry-pick, with the --no-commit flag. Then, add the desired file to stage.
    • It's recommended to stash your current changes before cherry-picking so as not to lose

  • When should I use stash vs. a branch?

    • Use git stash for quick context switches.
    • Use a branch if you’ll be away from the change for longer.

  • How do I squash multiple commits into one before merge?

    • Use git rebase -i HEAD~<n> and mark commits as squash or fixup.

  • How do I undo a commit that’s already pushed?

    • If you need to undo locally before pushing, use:

      git reset --soft HEAD~1

      (--soft keeps changes staged, --hard discards them).

    • If the commit is already pushed to remote, use:

      git revert <commit>

      This creates a new commit that safely reverses the change without rewriting history.