From ffa485c11b48444acf3adf1e3c1cb3eed16fad94 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Mon, 18 Nov 2024 14:46:26 -0700 Subject: feat(ci): Add release-please automation with VERSION (#2622) * Add VERSION file that Zephyr will pick up * Add release-please automation * Updated docs on commits messages, and PR process * Updated PR template to match. --- Release-As: 0.1.0 Co-authored-by: Cem Aksoylar --- .github/pull_request_template.md | 17 +--- .github/workflows/release-please.yml | 38 ++++++++ .pre-commit-config.yaml | 7 +- .release-please-manifest.json | 1 + app/VERSION | 13 +++ .../development/contributing/commit-messages.md | 70 -------------- .../docs/development/contributing/pull-requests.md | 103 +++++++++++++++++++++ docs/sidebars.js | 2 +- release-please-config.json | 9 ++ 9 files changed, 176 insertions(+), 84 deletions(-) create mode 100644 .github/workflows/release-please.yml create mode 100644 .release-please-manifest.json create mode 100644 app/VERSION delete mode 100644 docs/docs/development/contributing/commit-messages.md create mode 100644 docs/docs/development/contributing/pull-requests.md create mode 100644 release-please-config.json diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9e523a36c5..e37a95867d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,15 +1,8 @@ - + -## Board/Shield Check-list +## PR check-list -- [ ] This board/shield is tested working on real hardware -- [ ] Definitions follow the general style of other shields/boards upstream ([Reference](https://zmk.dev/docs/development/new-shield)) -- [ ] `.zmk.yml` metadata file added +- [ ] Branch has a [clean commit history](https://zmk.dev/docs/development/contributing/pull-requests#clean-commit-history) +- [ ] Additional tests are included, if changing behaviors/core code that is testable. - [ ] Proper Copyright + License headers added to applicable files (Generally, we stick to "The ZMK Contributors" for copyrights to help avoid churn when files get edited) -- [ ] General consistent formatting of DeviceTree files -- [ ] Keymaps do not use deprecated key defines (Check using the [upgrader tool](https://zmk.dev/docs/codes/keymap-upgrader)) -- [ ] `&pro_micro` used in favor of `&pro_micro_d/a` if applicable -- [ ] If split, no name added for the right/peripheral half -- [ ] Kconfig.defconfig file correctly wraps _all_ configuration in conditional on the shield symbol -- [ ] `.conf` file has optional extra features commented out -- [ ] Keyboard/PCB is part of a shipped group buy or is generally available in stock to purchase (OSH/personal projects without general availability should create a zmk-config repo instead) +- [ ] [Pre-commit](https://zmk.dev/docs/development/local-toolchain/pre-commit) used to check formatting of files, commit messages, etc. diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml new file mode 100644 index 0000000000..49fba29374 --- /dev/null +++ b/.github/workflows/release-please.yml @@ -0,0 +1,38 @@ +on: + push: + branches: + - main + - "v*.*-branch" + +permissions: + contents: write + pull-requests: write + +name: release-please + +jobs: + release-please: + runs-on: ubuntu-latest + steps: + - uses: googleapis/release-please-action@v4 + id: release + with: + token: ${{ secrets.ZMK_RELEASE_PLEASE_TOKEN }} + target-branch: ${{ github.ref_name }} + - uses: actions/checkout@v4 + if: ${{ steps.release.outputs.release_created }} + - name: create major, minor branch + if: ${{ steps.release.outputs.release_created && steps.release.outputs.patch == '0' }} + run: | + git remote add gh-token-branch "https://x-access-token:${{ secrets.ZMK_RELEASE_PLEASE_TOKEN }}@github.com/${{ github.repository }}.git" + git checkout -b v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}-branch + git push gh-token-branch v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}-branch + - name: tag major and minor versions + if: ${{ steps.release.outputs.release_created }} + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + git remote add gh-token "https://x-access-token:${{ secrets.ZMK_RELEASE_PLEASE_TOKEN }}@github.com/${{ github.repository }}.git" + git tag -d v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} || true + git tag -a v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} -m "Release v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}" + git push --force gh-token v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1c6d560cef..aa9c8d3960 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -16,7 +16,12 @@ repos: rev: v2.7.1 hooks: - id: prettier - exclude: ".git/COMMIT_EDITMSG" + exclude: | + (?x)^( + .git/COMMIT_EDITMSG| + CHANGELOG.md| + .release-please-manifest.json + )$ # Workaround for https://github.com/pre-commit/mirrors-prettier/issues/29 additional_dependencies: - prettier@2.8.7 diff --git a/.release-please-manifest.json b/.release-please-manifest.json new file mode 100644 index 0000000000..0967ef424b --- /dev/null +++ b/.release-please-manifest.json @@ -0,0 +1 @@ +{} diff --git a/app/VERSION b/app/VERSION new file mode 100644 index 0000000000..bce9f90bd5 --- /dev/null +++ b/app/VERSION @@ -0,0 +1,13 @@ +# x-release-please-start-major +VERSION_MAJOR = 0 +# x-release-please-end + +# x-release-please-start-minor +VERSION_MINOR = 0 +# x-release-please-end + +# x-release-please-start-patch +PATCHLEVEL = 1 +# x-release-please-end + +VERSION_TWEAK = 0 \ No newline at end of file diff --git a/docs/docs/development/contributing/commit-messages.md b/docs/docs/development/contributing/commit-messages.md deleted file mode 100644 index 241d118dff..0000000000 --- a/docs/docs/development/contributing/commit-messages.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Commit Messages ---- - -The ZMK project uses [conventional commits](https://www.conventionalcommits.org/) for their commit messages. This not only provides consistency for our commits, but also allows for release/versioning automation to determine the next version to release, generating changelogs, etc. - -Commit messages will be checked as part of our CI process by GitHub Actions. - -## Guidelines - -Commits should have the following: - -- A first line prefix that includes a [type](#types), as well as appropriate [scope](#scopes) in parentheses as needed. -- Following the prefix, a concise summary of the change, which documents the new behavior/feature/functionality in the positive (e.g. "wake from sleep now works with charlieplex kscan", not "fixed waked from sleep bug with charlieplex kscan driver"). -- A blank line following the first line. -- A body that provides more detail of the changes. This _may_ be a bulleted list or paragraph prose. -- An optional set of [git trailers](https://git-scm.com/docs/git-interpret-trailers#_description) for things like [GitHub keywords](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests) following a blank line. - -## Example - -Here is an example of a good commit message: - -``` -feat(boards): Add numpad layouts - -Added physical layouts for the following variants of numpads: - -- With and without extra top row -- 2U plus key or 1U plus and backspace keys -- 2U 0 key or 1U 0 and 00 keys -- Full 1U grid/macropad layout - -Other layouts exist, such as "southpaw" horizontally mirrored layouts, -and layouts with a fifth column, but those seem to be much less common. -``` - -## Pre-Commit - -To help make sure you don't need to wait for GitHub Actions to check your commits, you can [set up pre-commit](../local-toolchain/pre-commit.md) to check your commits as you create them. - -## Types - -The following commit types are used by ZMK: - -- `blog:` -- changes to our documentation found in the `docs/blog` directory -- `docs:` -- changes to our documentation found in the `docs/` directory, except blogs -- `feat:` -- changes that add a new feature -- `fix:` -- changes that fix existing functionality -- `refactor:` -- changes that refactor existing functionality without adding any new features -- `feat!:`/`refactor!:`/`fix!:` -- same as above, but indicates a breaking change. Examples would be changes to the public C API, renaming a board/shield, editing a board or shield to rename devicetree labels that may be used in keymaps, etc. -- `ci:` -- changes to our continuous integration setup with GitHub Actions, usually only for the files in `.github/workflows/` -- `chore:` -- grab bag type for small changes that don't fall into any of the above categories, including dependency updates for development tools and docs. - -## Scopes - -The following scopes are frequently used to further clarify the scope of the change: - -- `hid` -- changes to our general HID code -- `usb` -- changes specific to USB -- `ble` -- changes specific to BLE -- `power` -- changes to our power management code -- `split` -- changes to our split keyboard support -- `studio` -- changes to our ZMK Studio code -- `display` -- changes to to our display code -- `underglow` -- changes to to our RGB underglow support -- `backlight` -- changes to to our simple LED backlight support -- `behaviors` -- changes to to our core behavior code -- `core` -- changes to any other area of our core code -- `boards` -- changes to the in-tree boards -- `shields` -- changes to the in-tree shields diff --git a/docs/docs/development/contributing/pull-requests.md b/docs/docs/development/contributing/pull-requests.md new file mode 100644 index 0000000000..a95854758e --- /dev/null +++ b/docs/docs/development/contributing/pull-requests.md @@ -0,0 +1,103 @@ +--- +title: Pull Requests +--- + +Changes to ZMK's `main` branch are all done through pull requests, even for core committers. The following will help ensure an easier PR/review process for all involved. + +## Clean Commit History + +Before opening a PR, ensure your branch has a clean commit history, which allows our release automation to generate clean changelogs, and allows easier understanding of our commit history when investigating regressions, etc. + +A "clean" commit history satisfies the following: + +- Commit messages follow our [commit message conventions](#commit-messages). +- The sequence of commits should be well organized, with discrete commits used to break any combined work into smaller, cohesive changes if the scope of a given PR/change is larger. This allows for easier code review. You can usually accomplish this by amending (e.g. `git add foo && git commit --amend`) or by interactive rebasing (e.g. `git rebase -i upstream/main`) and squashing/rewording commits. +- Do not use merge commits to catch up with ZMK `main`, instead using rebasing to address any issues with divergence (e.g. `git rebase upstream/main`). + +### Commit Messages + +The ZMK project uses [conventional commits](https://www.conventionalcommits.org/) for their commit messages. This not only provides consistency for our commits, but also allows for release/versioning automation to determine the next version to release, generating changelogs, etc. + +Commit messages will be checked as part of our CI process by GitHub Actions. + +#### Guidelines + +Commits should have the following: + +- A first line prefix that includes a [type](#types), as well as appropriate [scope](#scopes) in parentheses as needed. +- Following the prefix, a concise summary of the change, which documents the new behavior/feature/functionality in the positive (e.g. "wake from sleep now works with charlieplex kscan", not "fixed waked from sleep bug with charlieplex kscan driver"). +- A blank line following the first line. +- A body that provides more detail of the changes. This _may_ be a bulleted list or paragraph prose. +- An optional set of [git trailers](https://git-scm.com/docs/git-interpret-trailers#_description) for things like [GitHub keywords](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests) following a blank line. + +#### Example + +Here is an example of a good commit message: + +``` +feat(boards): Add numpad layouts + +Added physical layouts for the following variants of numpads: + +- With and without extra top row +- 2U plus key or 1U plus and backspace keys +- 2U 0 key or 1U 0 and 00 keys +- Full 1U grid/macropad layout + +Other layouts exist, such as "southpaw" horizontally mirrored layouts, +and layouts with a fifth column, but those seem to be much less common. +``` + +#### Pre-Commit + +To help make sure you don't need to wait for GitHub Actions to check your commits, you can [set up pre-commit](../local-toolchain/pre-commit.md) to check your commits as you create them. + +#### Types + +The following commit types are used by ZMK: + +- `blog:` -- changes to our documentation found in the `docs/blog` directory +- `docs:` -- changes to our documentation found in the `docs/` directory, except blogs +- `feat:` -- changes that add a new feature +- `fix:` -- changes that fix existing functionality +- `refactor:` -- changes that refactor existing functionality without adding any new features +- `feat!:`/`refactor!:`/`fix!:` -- same as above, but indicates a breaking change. Examples would be changes to the public C API, renaming a board/shield, editing a board or shield to rename devicetree labels that may be used in keymaps, etc. +- `ci:` -- changes to our continuous integration setup with GitHub Actions, usually only for the files in `.github/workflows/` +- `chore:` -- grab bag type for small changes that don't fall into any of the above categories, including dependency updates for development tools and docs. + +#### Scopes + +The following scopes are frequently used to further clarify the scope of the change: + +- `hid` -- changes to our general HID code +- `usb` -- changes specific to USB +- `ble` -- changes specific to BLE +- `power` -- changes to our power management code +- `split` -- changes to our split keyboard support +- `studio` -- changes to our ZMK Studio code +- `display` -- changes to to our display code +- `underglow` -- changes to to our RGB underglow support +- `backlight` -- changes to to our simple LED backlight support +- `behaviors` -- changes to to our core behavior code +- `core` -- changes to any other area of our core code +- `boards` -- changes to the in-tree boards +- `shields` -- changes to the in-tree shields + +## Opening a PR + +Create a PR by visiting https://github.com/zmkfirmware/zmk/pulls and clicking "New pull request" and selecting your branch. GitHub should auto-populate a start of a description/body to your PR, but please make sure to supplement that with additional details about the change and make sure the check-list is complete in the PR template. + +Once created, the PR should automatically have reviewers assigned. + +## Review + +Depending on the area of change, different ZMK team members will review the PR. The ZMK project is a small team, so please be patient with the review timeline. You are welcome to send a polite request/nudge on our Discord server to draw attention to your PR if it has not gotten a response after a reasonable amount of time. + +## Merging + +Maintainers merging PRs will perform the following steps: + +1. Verify that the expected tests have all run, and are passing +1. Inspect the commits in the PR to confirm the commit messages not only are proper conventional commits, but have accurate descriptions and are using the correct type for the set of files changed by the commit(s). +1. Merge the PR using a squash-merge. If the PR includes multiple commits, then the squash message will be fixed up manually to remove the `* ` prefixes from each message section to ensure [release-please](https://github.com/googleapis/release-please) properly will parse the compound commit message. +1. Confirm the new/existing release PR is updated properly with the expected version number and changelog. diff --git a/docs/sidebars.js b/docs/sidebars.js index 3cdd84e638..e7975fb2d5 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -142,7 +142,7 @@ module.exports = { collapsed: true, items: [ "development/contributing/clean-room", - "development/contributing/commit-messages", + "development/contributing/pull-requests", "development/contributing/documentation", ], }, diff --git a/release-please-config.json b/release-please-config.json new file mode 100644 index 0000000000..d09fb98616 --- /dev/null +++ b/release-please-config.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json", + "bootstrap-sha": "2ded7919ebd63e0174bf5a412f6f01d6af0061c6", + "release-type": "simple", + "extra-files": ["app/VERSION"], + "packages": { + ".": {} + } +} -- cgit v1.2.3