diff --git a/docs/newbs_building_firmware_workflow.md b/docs/newbs_building_firmware_workflow.md index 99b32f0b713..a4d51132513 100644 --- a/docs/newbs_building_firmware_workflow.md +++ b/docs/newbs_building_firmware_workflow.md @@ -56,26 +56,21 @@ 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 + +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 +``` + +?> 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 -### 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\\qmk_keymap\` path location. - ### Add a JSON keymap Visit the [QMK Configurator](https://config.qmk.fm/#/) to create a keymap file: @@ -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.