From 3a13e5a387a8d3032c4ef4c5c0da35a403cacb80 Mon Sep 17 00:00:00 2001 From: zvecr Date: Thu, 12 Jan 2023 09:10:38 +0000 Subject: [PATCH 1/6] Add reusable workflow for qmk_keymap repo --- .github/workflows/qmk_keymap.yml | 80 ++++++++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 .github/workflows/qmk_keymap.yml diff --git a/.github/workflows/qmk_keymap.yml b/.github/workflows/qmk_keymap.yml new file mode 100644 index 000000000000..01be8593c5ec --- /dev/null +++ b/.github/workflows/qmk_keymap.yml @@ -0,0 +1,80 @@ +name: Build qmk_keymap repo + +on: + workflow_call: + +permissions: + contents: write + +jobs: + prep: + runs-on: ubuntu-latest + outputs: + matrix: ${{ steps.set-matrix.outputs.matrix }} + + steps: + - name: Checkout userspace + uses: actions/checkout@v3 + + - name: Configure build targets + id: set-matrix + run: | + data="" + delim="" + for file in *.json; do + data="${data}${delim}{\"file\":\"$file\"}" + delim="," + done + echo "matrix={\"include\":[$data]}" >> $GITHUB_OUTPUT + + build: + needs: prep + runs-on: ubuntu-latest + container: qmkfm/qmk_cli + + strategy: + fail-fast: false + matrix: ${{ fromJSON(needs.prep.outputs.matrix) }} + + steps: + - name: Checkout QMK + uses: actions/checkout@v3 + with: + repository: qmk/qmk_firmware + submodules: recursive + + - name: Checkout userspace + uses: actions/checkout@v3 + with: + path: users/${{ github.actor }} + + - name: Build firmware + run: qmk compile -j=4 "users/${{ github.actor }}/${{ matrix.file }}" + + - name: Archive firmware + uses: actions/upload-artifact@v3 + continue-on-error: true + with: + name: ${{ matrix.file }}_${{ github.actor }} + path: | + *.hex + *.bin + *.uf2 + + publish: + needs: build + runs-on: ubuntu-latest + + steps: + - uses: actions/download-artifact@v3 + + - uses: marvinpinto/action-automatic-releases@latest + if: always() + with: + repo_token: "${{ github.token }}" + automatic_release_tag: "latest" + title: "Latest Firmware" + files: | + **/*.hex + **/*.bin + **/*.uf2 From 50e7cb27ee4c34841d06ef003f4506e3cc4c7715 Mon Sep 17 00:00:00 2001 From: zvecr Date: Thu, 12 Jan 2023 10:31:44 +0000 Subject: [PATCH 2/6] stub out docs changes --- docs/newbs_building_firmware_workflow.md | 87 ++++-------------------- 1 file changed, 13 insertions(+), 74 deletions(-) diff --git a/docs/newbs_building_firmware_workflow.md b/docs/newbs_building_firmware_workflow.md index 99b32f0b7139..a4d511325131 100644 --- a/docs/newbs_building_firmware_workflow.md +++ b/docs/newbs_building_firmware_workflow.md @@ -56,25 +56,20 @@ If your GitHub account is not configured for [authenticated Git operations](http * [Personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) * [Connecting with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) -### 3. Create a repository +## Create a repository -You will need a personal GitHub repository to host your QMK code. Follow [this guide](https://docs.github.com/en/get-started/quickstart/create-a-repo#create-a-repository) to create one named `qmk_keymap`. Do not proceed to commit any files just yet. +You will need a personal GitHub repository to host your QMK code. The template provided at is pre-configured for the workflow detailed here. Follow [this guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template) and create a repo based off the template named `qmk_keymap`. +### Clone repository -## Initial Code Commit - -### Create template files - -Run the following commands in your computer to create a folder with a few template files: +Run the following commands in your computer to create a folder with a few template files (replacing `gh-username` with your GitHub user name): ``` -mkdir -p ~/qmk_keymap/.github/workflows -touch ~/qmk_keymap/.github/workflows/build.yml -touch ~/qmk_keymap/config.h -echo "SRC += source.c" > ~/qmk_keymap/rules.mk -echo "#include QMK_KEYBOARD_H" > ~/qmk_keymap/source.c +git clone https://github.com/gh-username/qmk_keymap ``` -?> For Windows user running MSYS, those commands will create the folder `qmk_keymap/` and its content in the `C:\Users\\qmk_keymap\` path location. +?> For Windows user running MSYS, the above command will create the folder `qmk_keymap/` and its content in the `C:\Users\\qmk_keymap\` path location. + +## Initial Code Commit ### Add a JSON keymap @@ -85,55 +80,6 @@ Visit the [QMK Configurator](https://config.qmk.fm/#/) to create a keymap file: 3. Customise the key layout according to your preference. 4. Select download next to **KEYMAP.JSON** and save the JSON file into the `~/qmk_keymap/` folder. -### Add a GitHub Action workflow - -Open the file `~/qmk_keymap/.github/workflows/build.yml` with your favorite [text editor](newbs_learn_more_resources.md#text-editor-resources), paste the following workflow content, and save it: -```yml -name: Build QMK firmware -on: [push, workflow_dispatch] - -jobs: - build: - runs-on: ubuntu-latest - container: qmkfm/qmk_cli - strategy: - fail-fast: false - matrix: -# List of keymap json files to build - file: - - username.json -# End of json file list - - steps: - - - name: Checkout QMK - uses: actions/checkout@v3 - with: - repository: qmk/qmk_firmware - submodules: recursive - - - name: Checkout userspace - uses: actions/checkout@v3 - with: - path: users/${{ github.actor }} - - - name: Build firmware - run: qmk compile "users/${{ github.actor }}/${{ matrix.file }}" - - - name: Archive firmware - uses: actions/upload-artifact@v3 - continue-on-error: true - with: - name: ${{ matrix.file }}_${{ github.actor }} - path: | - *.hex - *.bin - *.uf2 -``` -Replace `username.json` with the JSON file name that was downloaded from [QMK Configurator](https://config.qmk.fm/#/) in the previous step. - -!> Do note that the `build.yml` file requires ***proper indentation*** for every line. Incorrect spacing will trigger workflow syntax errors. - ### Commit files to GitHub If you have completed all steps correctly, the folder `qmk_keymap/` will contain the following files: @@ -147,15 +93,13 @@ If you have completed all steps correctly, the folder `qmk_keymap/` will contain |-- username.json ``` -To commit and push them into GitHub, run the following commands (replacing `gh-username` with your GitHub user name): +To commit and push them into GitHub, run the following commands: ``` cd ~/qmk_keymap -git init git add -A git commit -m "Initial QMK keymap commit" git branch -M main -git remote add origin https://github.com/gh-username/qmk_keymap.git -git push -u origin main +git push ``` ?> Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace `https://github.com/gh-username/qmk_keymap.git` with `git@github.com:gh-username/qmk_keymap.git` in the remote origin command above. @@ -165,8 +109,9 @@ Files committed to GitHub in the previous step will automatically trigger the wo 1. Visit your "**qmk_keymap**" repository page on [GitHub](https://github.com/). 2. Select **Actions** tab to display the "**Build QMK Firmware**" workflow. 3. Select that workflow to display its run from the last commit. -4. Successfully compiled firmware will be under the "**Artifacts**" section. -5. If there are build errors, review the job log for details. +4. If there are build errors, review the job log for details. + +Successfully compiled firmware will be under the "**Releases**" section, . Download and flash the firmware file into your keyboard using [QMK Toolbox](https://docs.qmk.fm/#/newbs_flashing?id=flashing-your-keyboard-with-qmk-toolbox). @@ -177,12 +122,6 @@ This setup and workflow relies on the QMK [Userspace](https://docs.qmk.fm/#/feat * Keymap layout files must be retained in JSON format and cannot be converted to `keymap.c`. * User callback and functions (e.g. `process_record_user()`) can be placed in the `source.c` file. -* Multiple keymap JSON files can be built in the same workflow. List them under `matrix.file:`, e.g.: -```yml - file: - - planck.json - - crkbd.json -``` * Code changes will require Git commit into GitHub to trigger the build workflow. From 97783816b18c63dc5c17701e0de52c748b6d339f Mon Sep 17 00:00:00 2001 From: zvecr Date: Thu, 12 Jan 2023 11:20:37 +0000 Subject: [PATCH 3/6] parametrize qmk repo --- .github/workflows/qmk_keymap.yml | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/.github/workflows/qmk_keymap.yml b/.github/workflows/qmk_keymap.yml index 01be8593c5ec..5eee0e33a8e1 100644 --- a/.github/workflows/qmk_keymap.yml +++ b/.github/workflows/qmk_keymap.yml @@ -2,6 +2,17 @@ name: Build qmk_keymap repo on: workflow_call: + inputs: + qmk_repo: + description: 'qmk_firmware repo to build against' + default: 'qmk/qmk_firmware' + required: false + type: string + qmk_ref: + description: 'qmk_firmware branch to build against' + default: 'master' + required: false + type: string permissions: contents: write @@ -40,7 +51,8 @@ jobs: - name: Checkout QMK uses: actions/checkout@v3 with: - repository: qmk/qmk_firmware + repository: ${{ secrets.qmk_repo }} + ref: ${{ secrets.qmk_ref }} submodules: recursive - name: Checkout userspace From 4a470685037fce216444002af2c5331b0f9c6acb Mon Sep 17 00:00:00 2001 From: zvecr Date: Thu, 12 Jan 2023 11:27:42 +0000 Subject: [PATCH 4/6] parametrize qmk repo --- .github/workflows/qmk_keymap.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/qmk_keymap.yml b/.github/workflows/qmk_keymap.yml index 5eee0e33a8e1..89a611facbfd 100644 --- a/.github/workflows/qmk_keymap.yml +++ b/.github/workflows/qmk_keymap.yml @@ -51,8 +51,8 @@ jobs: - name: Checkout QMK uses: actions/checkout@v3 with: - repository: ${{ secrets.qmk_repo }} - ref: ${{ secrets.qmk_ref }} + repository: ${{ inputs.qmk_repo }} + ref: ${{ inputs.qmk_ref }} submodules: recursive - name: Checkout userspace From 57b14f647aadd94b10db7e642fb84bca6ddaf698 Mon Sep 17 00:00:00 2001 From: zvecr Date: Thu, 12 Jan 2023 11:36:41 +0000 Subject: [PATCH 5/6] Install any missing cli deps --- .github/workflows/qmk_keymap.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/qmk_keymap.yml b/.github/workflows/qmk_keymap.yml index 89a611facbfd..fb0ac4138a89 100644 --- a/.github/workflows/qmk_keymap.yml +++ b/.github/workflows/qmk_keymap.yml @@ -60,6 +60,9 @@ jobs: with: path: users/${{ github.actor }} + - name: Install missing dependencies + run: pip3 install -r requirements.txt + - name: Build firmware run: qmk compile -j=4 "users/${{ github.actor }}/${{ matrix.file }}" @@ -86,6 +89,7 @@ jobs: repo_token: "${{ github.token }}" automatic_release_tag: "latest" title: "Latest Firmware" + prerelease: false files: | **/*.hex **/*.bin From ed5f5236903ef8a784f8927e9fd6b3da1246b86e Mon Sep 17 00:00:00 2001 From: zvecr Date: Thu, 12 Jan 2023 18:16:09 +0000 Subject: [PATCH 6/6] docs shuffle --- docs/newbs_building_firmware_workflow.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/newbs_building_firmware_workflow.md b/docs/newbs_building_firmware_workflow.md index a4d511325131..70547f3fc929 100644 --- a/docs/newbs_building_firmware_workflow.md +++ b/docs/newbs_building_firmware_workflow.md @@ -67,6 +67,8 @@ Run the following commands in your computer to create a folder with a few templa git clone https://github.com/gh-username/qmk_keymap ``` +?> Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace `https://github.com/gh-username/qmk_keymap.git` with `git@github.com:gh-username/qmk_keymap.git` in the remote origin command above. + ?> For Windows user running MSYS, the above command will create the folder `qmk_keymap/` and its content in the `C:\Users\\qmk_keymap\` path location. ## Initial Code Commit @@ -98,10 +100,8 @@ To commit and push them into GitHub, run the following commands: cd ~/qmk_keymap git add -A git commit -m "Initial QMK keymap commit" -git branch -M main git push ``` -?> Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace `https://github.com/gh-username/qmk_keymap.git` with `git@github.com:gh-username/qmk_keymap.git` in the remote origin command above. ### Review workflow output @@ -111,7 +111,9 @@ Files committed to GitHub in the previous step will automatically trigger the wo 3. Select that workflow to display its run from the last commit. 4. If there are build errors, review the job log for details. -Successfully compiled firmware will be under the "**Releases**" section, . +### Flashing + +Successfully compiled firmware will be under the "**Releases**" section, . Download and flash the firmware file into your keyboard using [QMK Toolbox](https://docs.qmk.fm/#/newbs_flashing?id=flashing-your-keyboard-with-qmk-toolbox).