From 300e62a9fc13411c4d13c3393d18a917c6323658 Mon Sep 17 00:00:00 2001
From: Quentin <bstkbd@gmail.com>
Date: Fri, 2 Aug 2024 14:34:39 +0200
Subject: [PATCH] add userspace info draft

---
 fw/compile-firmware.md | 92 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 85 insertions(+), 7 deletions(-)

diff --git a/fw/compile-firmware.md b/fw/compile-firmware.md
index 0af9934..c06b1d1 100644
--- a/fw/compile-firmware.md
+++ b/fw/compile-firmware.md
@@ -10,7 +10,6 @@ parent: Firmware
 1. TOC
 {:toc}
 
-
 # Introduction
 
 The [BastardKB QMK repository](https://github.com/bastardkb/bastardkb-qmk) contains the firmware code and releases for the Bastard Keyboards Charybdis boards.
@@ -21,17 +20,70 @@ This page details how to compile your own firmware. Building from source is usef
 
 If that seems too complicated, you can also use one of the default releases, or VIA.
 
-# Requirements 
+# Pre-requisites
+
+## Working QMK environment
+
+Make sure you have a functional QMK environment. See [QMK Docs](https://docs.qmk.fm/#/newbs) for details. At this point, **you don't need** to run `qmk setup`.
 
-1. Follow the [QMK docs](https://docs.qmk.fm/#/getting_started_build_tools) to setup your environment
-2. Clone the [BastardKB QMK repository](https://github.com/bastardkb/bastardkb-qmk)
+## BastardKb QMK fork
 
-# Building your firmware
+We maintain our own QMK fork. It serves as the primary source of truth, and contains the latest changes and innovation.
+While we regularly push to the main QMK repository, the BKB QMK fork is the one that's most up to date.
 
-To build a firmware, use the `bkb-master` branch:
+Clone the BKB QMK repository, using either github desktop or the command line, and switch to the `bkb-master` branch:
 
 ```shell
+git clone https://github.com/bastardkb/bastardkb-qmk
 git checkout origin/bkb-master
+```
+
+Now that you've cloned the repository, `cd` into it and set it as the default local QMK repository. You also need to do this if you had a previous, separate QMK installation.
+
+```shell
+cd bastardkb-qmk
+qmk config user.qmk_home="$(realpath .)" 
+```
+
+{: .note }
+If you have multiple QMK installations, you will need to manually set the qmk home path again to use the other ones.
+
+## BastardKb userspace
+
+While the QMK repository contains the logic behind the keyboards, the keymaps are in the userspace repository.
+
+In a separate folder, clone the BKB QMK repository, using either github desktop or the command line:
+
+
+```shell
+git clone https://github.com/bastardkb/qmk_userspace
+```
+
+Next, `cd` into the repository and enable userspace:
+
+```shell
+cd qmk_userspace
+qmk config user.overlay_dir="$(realpath .)"
+```
+
+## Github actions
+
+// TODO screenshot enable actions workflows
+
+// TODO mroe details, screenshots
+actions tab -- "I understand my workflows, go ahead and enable them"
+
+1. In the GitHub Actions tab, enable workflows
+2. Push your changes above to your forked GitHub repository
+3. Look at the GitHub Actions for a new actions run
+4. Wait for the actions run to complete
+5. Inspect the Releases tab on your repository for the latest firmware build
+
+# Compiling with console
+
+Once in the QMK Userspace repository, compiling a keymap works the same as normal:
+
+```shell
 qmk compile -c -kb bastardkb/{keyboard} -km {keymap}
 ```
 
@@ -58,12 +110,38 @@ To build *any* keymap with Via support, simply add the following argument to the
 qmk compile -c -kb {keyboard} -km default -e VIA_ENABLE=yes
 ```
 
+# Compiling with Github Actions
+
+If you clone the BastardKB Userspace repository, it is alredy configured to work with the BastardKB QMK fork.
+
+If you created your own keymap, you will need to add it to the list of keympaps to be compiled in `qmk.json`, for example:
+
+```shell
+{
+    "userspace_version": "1.0",
+    "build_targets": [
+        ["bastardkb/charybdis/4x6", "my-keymap"]
+    ]
+}
+```
+
+We also recommend deleting the other keymaps if you don't use them, as it'll make the action run faster.
+
+# Creating your own keymap
+
+// TODO
+
+# Contributing your own keymap
+
+// TODO
+
 # Flashing your keyboard
 
 Once you compiled your `uf2` image, you can flash your keyboard.
 
 For how to flash your keyboard, take a look at the [how to flash your keyboard page][flashing].
 
+
 ---
 
-[flashing]: {{site.baseurl}}/fw/flashing.html
+[flashing]: {{site.baseurl}}/fw/flashing.html
\ No newline at end of file