Skip to content

Latest commit

 

History

History
52 lines (39 loc) · 3.9 KB

CONTRIBUTING.md

File metadata and controls

52 lines (39 loc) · 3.9 KB
Raw

Contributing

Internal Contributions

This section outlines best practices for internal contributors, these are people who have direct access to the repository. We currently do not have a process for external contributors but will add a section for that when applicable.

Best Practices

  • It's recommended to branch directly from the repo for easier collaboration. This doc will assume you branch from origin/master.
  • All changes to master should first be a pull request.
  • PR titles should conform to conventional commits.
  • Branch names should ideally be generated by Linear issues, but otherwise there's no particular naming convention.
  • Try to keep PRs focused on a single feature, bug, or issue.
  • Document motivation for change in the PR, i.e. link to issue or describe reason for change.
  • If the change is relatively complex, use the PR description to summarize what code was changed and why.
  • If you want to make multiple changes in a PR, make sure they are small and document the motivation for each.
  • Include screenshots when applicable. Before and after is ideal, though after, alone, is acceptable.
  • Tag at least 2 reviewers. Most PRs should be merged in after 2 approvals, but low risk or high urgency PRs can be merged with 1.
  • The owner of the PR merges the PR once approved.
  • If changes are UI oriented, notify QA for additional approval above the technical review before PR is merged.

Feature Branches

Use feature branches when you need to split up changes to the app which may break the app or introduce incomplete features.

  • Name the branch based on the epic, story, feature or issue. Ideally, this name links back to the original shortcut card.
  • Denote a feature branch with the prefix "epic/", for example "epic/l1tol2". We will reserve "epic" for feature branches.
  • Open pull requests to feature branch, following the same best practices.
  • Nominate someone to occasionally rebase feature branch to master when working as a team.
  • QA should review individual PR's before merging to feature branch, though a final holistic QA process should be done before merging feature branch to master.
  • When merging a feature branch, rebase it onto master before merge. See following sections for more information.

Maintaining Branches

To avoid long-lived branches diverging from master, it's recommended to rebase rather than merge changes from master. This makes it easy to spot problems during review as the commit history should only show your changes. The frequency of rebasing is dependent on how quickly your branch is getting out of date, but you should generally rebase soon after you see changes on your upstream branch. It's also recommended to rebase before opening a PR.

Quick Rebase Guide

This guide assumes you have a branch in the repository, and not a fork, and the github repository is named origin.

  1. Start on your branch. Ensure there are no uncommitted changes, if so commit or stash them.
  2. git fetch origin master - This will fetch latest changes to master without switching branches. This assumes your upstream repository is names "origin".
  3. git rebase HEAD~X --onto origin/master - Rebase your changes on top of the latest changes on master, where X is the number of commits you have made to your branch.
  4. If conflicts occur, fix them, git add them and git rebase --continue until the rebase is complete.
  5. If you have stashed changes before the rebase, git stash pop them and commit them or keep working.
  6. When updating an existing PR, you can't just git push, but you must git push -f or git push --force-with-lease.

For more details on rebasing, see this guide