docs shuffle

.github/workflows/qmk_keymap.yml

@@ -0,0 +1,96 @@
+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
+
+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: ${{ inputs.qmk_repo }}
+        ref:  ${{ inputs.qmk_ref }}
+        submodules: recursive
+
+    - name: Checkout userspace
+      uses: actions/checkout@v3
+      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 }}"
+
+    - 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"
+        prerelease: false
+        files: |
+          **/*.hex
+          **/*.bin
+          **/*.uf2

docs/newbs_building_firmware_workflow.md

@@ -56,26 +56,23 @@ 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 <https://github.com/qmk/qmk_keymap> 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
+
+Run the following commands in your computer to create a folder with a few template files (replacing `gh-username` with your GitHub user name):
+```
+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\<windows_username>\qmk_keymap\` path location.
 
 ## Initial Code Commit
 
-### Create template files
-
-Run the following commands in your computer to create a folder with a few template files:
-```
-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
-```
-
-?> For Windows user running MSYS, those commands will create the folder `qmk_keymap/` and its content in the `C:\Users\<windows_username>\qmk_keymap\` path location.
-
 ### Add a JSON keymap
 
 Visit the [QMK Configurator](https://config.qmk.fm/#/) to create a keymap file:
@@ -85,55 +82,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,17 +95,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 push
-git remote add origin https://github.com/gh-username/qmk_keymap.git
-git push -u origin main
 ```
-?> 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
 
@@ -165,8 +109,11 @@ 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.
+4. If there are build errors, review the job log for details.
-5. If there are build errors, review the job log for details.
+
+### Flashing
+
+Successfully compiled firmware will be under the "**Releases**" section, <https://github.com/qmk/qmk_keymap/releases/tag/latest>.
 
 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 +124,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.