Skip to content

Pull Request and Commit workflow notes

Darcy Wong edited this page Feb 14, 2020 · 36 revisions

Commit messages

fix(windows): Re-attaches the widget plug which had fallen out

Fixes #1234. The widget plug was wonky so I attached paper clips
so it would stay in more firmly.

Commit

  • We use the following commit types:

    • fix: addresses a bug in the codebase. Should almost always have a corresponding issue. GitHub label bug should be applied.
    • feat: adds a new feature to the codebase. GitHub label enhancement should be applied.
    • change: makes a modification that is neither a bug fix nor a feature. Corresponds to GitHub label modification. You may find docs:, style:, or refactor: are a better fit.
    • chore: makes a change to infrastructure which doesn't fit the above categories.
    • docs: changes documentation only. Use GitHub label modification.
    • style: is a format-only change. No change to code behaviour! Use GitHub label modification.
    • refactor: applies for any small or large refactoring of the codebase, renaming variables, restructuring code. Use GitHub label modification.
    • test: applies for unit test changes. Use GitHub label modification.
    • auto: for automatically-created PRs, such as version increments. Use GitHub label auto
  • If appropriate, include one scope in your commit message. A scope may include a sub-scope; if the work does not belong in a sub-scope, use the parent scope. Scopes correspond roughly to folder names.

    • android -- Keyman for Android
      • android/app -- KMAPro project, including configuration
      • android/browser -- Web browser in KMAPro project
      • android/engine -- KMEA project, including system keyboard extension
      • android/oem -- Android projects in oem folder
    • ci -- Continuous Integration; use a platform scope in preference to this scope if possible
    • common -- use this for resources and common folders and other common code
      • common/core -- Keyman Core project
      • common/lmlayer -- Predictive Text components (note GitHub label is currently web-lm-layer)
    • developer -- Keyman Developer (including Windows and JS components)
      • developer/compiler -- Compilers (command line and within IDE)
      • developer/ide -- Any IDE-related work
      • developer/tools -- Other tools (e.g. kmdecomp, kmconvert)
    • ios -- Keyman for iPhone and iPad
      • ios/app -- Keyman project
      • ios/browser -- Web browser within Keyman project
      • ios/engine -- KeymanEngine project
      • ios/oem -- iOS projects in oem folder
    • linux -- Keyman for Linux
      • linux/config -- Configuration scripts
      • linux/engine -- Keyman Engine
      • linux/ibus -- Ibus Integration
      • linux/oem -- Linux projects in oem folder
    • mac -- Keyman for macOS
      • mac/config -- Configuration utility
      • mac/engine -- Keyman Engine for macOS
      • mac/oem -- macOS projects in oem folder
    • web -- KeymanWeb
      • web/engine -- KeymanWeb Engine; components common to web, android and ios
      • web/oem -- web projects in oem folder
      • web/ui -- KeymanWeb UI components
    • windows -- Keyman Desktop
      • windows/config -- Keyman Configuration
      • windows/engine -- keyman, keyman32, keyman64, keymanx64, kmcomapi, tsysinfo and other Engine projects
      • windows/oem -- Windows projects in oem folder
  • If your commit crosses multiple scopes, consider breaking it into multiple commits. This helps reviewers!

  • Include text "Fixes #1234" in the commit message to automatically link and close issue #1234 when the PR merges.

  • Try and make your first line 50 chars or less, and wrap subsequent lines at 72 chars. The "Fixes #1234" text does not have to be on the first line. This may be difficult to achieve so don't stress too much!

  • Tip: If you use VS Code as your default editor for Git for Windows (an option at install time), then it will turns your text red when it overflows and shows a 72 character margin in the commit message editor.

  • How to setup up a git commit-msg hook to enforce conventional commits

Branch Names

We use the same types and scopes as listed above for branch names. The basic format is:

<type>/<scope>/[cherry-pick/][<issuenum>-][name-kebab-case]

For cherry-picked branches we should add the cherry-pick/ component. If the branch addresses a specific issue, try and include the issue number. Keep names lower case and use hyphens to separate words ('kebab case').

Pull Requests

Workflow - draft and work-in-progress pull requests

  • Push early to a draft PR: it's a backup, it helps with tracking progress, and keeps us thinking about getting our PRs to completion.
  • While in draft, feel free to rebase and force push in order to better organise commits.
  • Once a PR exits draft, do not use force pushes. Force pushes make it hard for reviewers to track changes in response to reviews.
  • If a (non-draft) PR needs significant work, then apply the work-in-progress label to help others.

Pull Request body

  • Include "Fixes #1234" in the body of the initial PR comment to make it more visible to reviewers.
  • Make sure that you detail what is changing in the PR and what the potential impacts are.
  • If you start from a commit message, remember that the pull request body should not need to be manually wrapped (i.e. you may want to unwrap it).

Pull Request Reviews

  • When a PR is ready for review, you can request a review using GitHub, but also share a link to the PR in Slack #general and include the :stampy: emoji. Be witty.

Requesting User Tests

  • In a PR comment, include a ## User Testing section with details on what needs to be tested by our test users.
  • If no user testing is necessary, note the reason, e.g. Not required (dev only).
  • If possible, use a checklist that can be ticked off by the tester (Markdown: - [ ] foo).
  • Tag @MakaraSok (lead tester) in the same comment so that he is notified for testing.

Testers: Recording test results

  • Add a PR comment detailing the testing undertaken and results.
  • Tick off passing tests in the original user testing comment.

Failing tests

  • If a test does not pass, add a Request Changes code review (in Files changed area) with details on what failed.
  • You might want to use **FAIL:** in your comment to make it more visible that tests didn't pass.
  • After the code is fixed, and the test passes, you will need to add an Approve code review so that the PR can be merged.

Metadata

Labels

  • Make sure your pull request labels correspond to the commits included. We have scoping labels for each platform, a few sub-scopes, and type labels bug, enhancement, and modification.
  • If your PR is a cherry pick of another PR to another branch (e.g. from master to stable-12.0), include cherry-pick.
  • For PRs that target a stable release, include stable.
  • We prefer to leave a PR in draft if it is not ready, but you can mark a PR with work-in-progress if it is no longer in draft but is not ready (e.g. significant work has been identified on it)

Milestone

  • You should almost always tag with the current sprint. In rare cases, you might tag a PR with future. Don't tag a PR with subsequent sprint tags -- they will be rolled over to the next sprint automatically anyway.

Merging PRs

  • Currently, we use merge commits.

Clone this wiki locally