Repository navigation
Pull Request and Commit workflow notes
- We use Conventional Commits for commit messages and PR titles, for example:
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.
-
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 finddocs:,style:, orrefactor: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 forresourcesandcommonfolders 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
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').
- 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-progresslabel to help others.
- 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).
- 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.
- In a PR comment, include a
## User Testingsection 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.
- Add a PR comment detailing the testing undertaken and results.
- Tick off passing tests in the original user testing comment.
- 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.
- 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, andmodification. - If your PR is a cherry pick of another PR to another branch (e.g. from
mastertostable-12.0), includecherry-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-progressif it is no longer in draft but is not ready (e.g. significant work has been identified on it)
- 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.
- Currently, we use merge commits.