feat(ci): Add release-please automation with VERSION (#2622)

petejohanson · caksoylar · web-flow · commit ffa485c11b48 · 2024-11-18T16:46:26.000-05:00
* 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 &lt;caksoylar@users.noreply.github.com&gt;
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -1,15 +1,8 @@
-<!-- If you're adding a board/shield please fill out this check-list, otherwise you can delete it -->
+<!-- Note: ZMK is generally not accepting PRs for new keyboards. New generic controller PRs *may* still be accepted, please discuss on the Discord server first. -->
 
-## 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
@@ -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
@@ -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
@@ -0,0 +1 @@
+{}
diff --git a/app/VERSION 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
diff --git a/docs/docs/development/contributing/pull-requests.md b/docs/docs/development/contributing/pull-requests.md
@@ -1,12 +1,26 @@
 ---
-title: Commit Messages
+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
+#### Guidelines
 
 Commits should have the following:
 
@@ -16,7 +30,7 @@ Commits should have the following:
 - 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
+#### Example
 
 Here is an example of a good commit message:
 
@@ -34,11 +48,11 @@ 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
+#### 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
+#### Types
 
 The following commit types are used by ZMK:
 
@@ -51,7 +65,7 @@ The following commit types are used by ZMK:
 - `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
+#### Scopes
 
 The following scopes are frequently used to further clarify the scope of the change:
 
@@ -68,3 +82,22 @@ The following scopes are frequently used to further clarify the scope of the cha
 - `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
@@ -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
@@ -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": {
+    ".": {}
+  }
+}
