commits: Add docs for one commit per package

astro.config.mjs

@@ -163,6 +163,7 @@ export default defineConfig({
                 { slug: "packaging/workflow/creating-a-new-recipe" },
                 { slug: "packaging/workflow/updating-an-existing-recipe" },
                 { slug: "packaging/workflow/building-and-testing-packages" },
+                { slug: "packaging/workflow/using-git" },
                 { slug: "packaging/workflow/submitting-a-pr" },
                 { slug: "packaging/workflow/checking-for-updates" },
               ],

src/content/docs/Packaging/Workflow/building-and-testing-packages.mdx

@@ -1,6 +1,6 @@
 ---
 title : 'Building and testing packages'
-lastUpdated: 2026-01-25T12:00:00+00:00
+lastUpdated: 2026-09-19T16:00:00Z
 description: "How to build and test packages locally on your system"
 license: "CC-BY-SA-4.0"
 copyright: "Copyright © 2025 aerynOS Developers"
@@ -52,5 +52,5 @@ sudo moss install "package name"
 Once you have tested the package, you can make a submission for including the update in the repository.
 
 <Aside type="tip" title="How to submit pull requests">
-  To find guidance on how to submit a pull request (PR), you can refer to our [submit a pull request](/packaging/workflow/submitting-a-pr) page.                    s
+  Commit each package on its own, then open a pull request. See [Using git](/packaging/workflow/using-git/) for the one-commit-per-package rule and [Submitting a PR](/packaging/workflow/submitting-a-pr/) for the pull request guidelines.
 </Aside>

src/content/docs/Packaging/Workflow/creating-a-new-recipe.mdx

@@ -1,6 +1,6 @@
 ---
 title: 'Creating a new package recipe'
-lastUpdated: 2026-01-25T12:00:00+00:00
+lastUpdated: 2026-09-19T16:00:00Z
 description: "Creating a new package recipe from scratch"
 license: "CC-BY-SA-4.0"
 copyright: "Copyright © 2025 aerynOS Developers"
@@ -332,3 +332,5 @@ security:
 ## Build and test the package
 
 Once you have made the relevant changes to the package, you will need to build it locally. Refer to the [Building and Testing packages](/packaging/workflow/building-and-testing-packages/) page on guidance of how to do this.
+
+When the package is ready, commit it on its own. aerynOS requires **one commit per package**. See [Using git](/packaging/workflow/using-git/) and [Submitting a PR](/packaging/workflow/submitting-a-pr/) for the commit workflow and message format.

src/content/docs/Packaging/Workflow/preparing-for-packaging.mdx

@@ -1,6 +1,6 @@
 ---
 title: 'Preparing for packaging'
-lastUpdated: 2026-01-25T12:00:00+00:00
+lastUpdated: 2026-09-19T16:00:00Z
 description: "Preparing for packaging on aerynOS"
 license: "CC-BY-SA-4.0"
 copyright: "Copyright © 2025 aerynOS Developers"
@@ -44,3 +44,5 @@ You can check what branch you are on and what branches you have in your reposito
 ```bash
 git branch -a
 ```
+
+When you are ready to commit, aerynOS requires **one commit per package**. [Using git](/packaging/workflow/using-git/) covers that rule, the git hooks, and the common git commands we use.

src/content/docs/Packaging/Workflow/prerequisites.mdx

@@ -1,6 +1,6 @@
 ---
 title: 'Prerequisites'
-lastUpdated: 2025-07-23T12:50:00+02:00
+lastUpdated: 2026-09-19T16:00:00Z
 description: "Prerequisites for building packages on Aeryn OS"
 license: "CC-BY-SA-4.0"
 copyright: "Copyright © 2025 aerynOS Developers"
@@ -63,6 +63,8 @@ just init
 
 This will setup git hooks that will lint for the most common packaging errors upon git commit, as well as fill out commit message templates for you to edit as appropriate.
 
+See [Using git](/packaging/workflow/using-git/) for how those hooks work, the one-commit-per-package rule, and a reference of the git commands we use.
+
 
 ### Setting up `git diff` auto-conversion of `manifest.*.bin` files
 

src/content/docs/Packaging/Workflow/submitting-a-pr.mdx

@@ -1,6 +1,6 @@
 ---
 title: 'Submitting a PR'
-lastUpdated: 2026-01-11T21:22:00
+lastUpdated: 2026-09-19T16:00:00Z
 description: "How to submit a PR into the aerynOS repository"
 license: "CC-BY-SA-4.0"
 copyright: "Copyright © 2025 aerynOS Developers"
@@ -10,7 +10,31 @@ import { Aside } from "@astrojs/starlight/components";
 
 # Submitting packages to aerynOS repository
 
-Once you have prepared your package, you can submit it to the aerynOS repository by creating a pull request (PR). There are certain guidelines to follow when submitting a PR:
+Once you have prepared your package, you can submit it to the aerynOS repository by creating a pull request (PR). There are certain guidelines to follow when submitting a PR.
+
+## One commit per package
+
+aerynOS requires **one commit per package**. Each recipe you add or change is its own commit. Do not combine several packages into one commit, and do not leave multiple commits for the same package.
+
+A pull request may still contain several commits when you add a package plus new dependencies — each dependency is one commit:
+
+```
+libfoo: Add at v1.0.0
+libbar: Add at v2.1.0
+mypackage: Add at v3.4.5
+```
+
+How to create those commits is covered in [Using git](/packaging/workflow/using-git/).
+
+## Push the branch and open the pull request
+
+After each package on the branch has been committed:
+
+```bash
+git push -u origin HEAD
+```
+
+Then open a pull request from your fork against `aerynOS/recipes` on GitHub. GitHub does not offer a native template picker, so use the **Preview** tab in the pull request description to choose the template that matches your change (new recipe, recipe update, bug fix, and so on) and fill it in completely.
 
 ## Naming Pull Requests
 

src/content/docs/Packaging/Workflow/updating-an-existing-recipe.mdx

@@ -1,6 +1,6 @@
 ---
 title : 'Updating an existing package recipe'
-lastUpdated: 2026-01-25T12:00:00+00:00
+lastUpdated: 2026-09-19T16:00:00Z
 description: "How to update an existing package recipe"
 license: "CC-BY-SA-4.0"
 copyright: "Copyright © 2025 aerynOS Developers"
@@ -70,3 +70,5 @@ If there are further changes required to the `stone.yaml` recipe file, you can e
 ## Build and test the package
 
 Once you have made the relevant changes to the package, you will need to build it locally. Refer to the [Building and Testing packages](/packaging/workflow/building-and-testing-packages/) page on guidance of how to do this.
+
+When the package is ready, commit it on its own. aerynOS requires **one commit per package**. See [Using git](/packaging/workflow/using-git/) and [Submitting a PR](/packaging/workflow/submitting-a-pr/) for the commit workflow and message format.

src/content/docs/Packaging/Workflow/using-git.mdx

@@ -0,0 +1,150 @@
+---
+title: 'Using git'
+lastUpdated: 2026-09-19T16:00:00Z
+description: "One commit per package, git hooks, and common git commands"
+license: "CC-BY-SA-4.0"
+copyright: "Copyright © 2025 aerynOS Developers"
+---
+import { Aside } from '@astrojs/starlight/components';
+
+
+Packaging work happens in the [recipes](https://github.com/aerynOS/recipes) git repository. This page covers the one-commit-per-package rule, the git hooks installed by `just init`, and the git commands we use day to day.
+
+If this is your first time using git or GitHub, start with GitHub's [Get started](https://docs.github.com/en/get-started) guide, then come back here for aerynOS-specific conventions.
+
+## One commit per package
+
+aerynOS requires **one commit per package**. Each recipe you add or change gets its own commit.
+
+- Do not combine multiple packages into a single commit.
+- Do not leave multiple commits for the same package in a pull request.
+- A pull request may contain several commits when you add a package plus new dependencies. Each dependency is still its own commit.
+
+```
+libfoo: Add at v1.0.0
+libbar: Add at v2.1.0
+mypackage: Add at v3.4.5
+```
+
+This keeps reviews focused, makes `git bisect` useful, and keeps the history readable. The same rule applies to updates and fixes: one package, one commit.
+
+If you need to change a package after you have already committed it, fold those changes into the existing commit instead of adding a second one. See [Amending an existing package commit](#amending-an-existing-package-commit).
+
+<Aside type="caution" title="Do not squash a multi-package PR into one commit">
+  When a pull request contains several packages, keep each package as its own commit. Squashing the branch into a single commit before merge hides which files belong to which package.
+</Aside>
+
+
+## Git hooks
+
+The [prerequisites](/packaging/workflow/prerequisites/) page has you run `just init` in the recipes repository. That installs two git hooks that run automatically when you commit:
+
+| Hook | What it does |
+|------|----------------|
+| `prepare-commit-msg` | Prefills the commit title from the staged recipe so you start from `name: Add at v<version>`, `name: Update to v<version>`, or `[NFC] name:`. |
+| `pre-commit` | Runs package checks on the files you staged. Common packaging errors reject the commit until you fix them. |
+
+Commit from the recipe directory so the hooks can see the recipe:
+
+```bash
+chpkg nano
+git commit
+```
+
+The `prepare-commit-msg` hook looks at the staged `stone.yaml` and `manifest.x86_64.jsonc` in the current directory and chooses a title:
+
+- `name: Add at v<version>` when this is the first release of the package
+- `name: Update to v<version>` when the version changed
+- `[NFC] name: ` when `stone.yaml` changed but the package was not rebuilt (no new manifest)
+- `name: ` for other recipe changes, such as a fix that you then describe
+
+Edit the prefilled title and complete the rest of the [commit message](/packaging/workflow/submitting-a-pr/#commit-message-format) before saving.
+
+
+## Committing a package
+
+After you have [built and tested](/packaging/workflow/building-and-testing-packages/) the package:
+
+```bash
+chpkg nano
+git status
+git diff
+git add stone.yaml manifest.x86_64.bin manifest.x86_64.jsonc monitoring.yaml
+# include pkg/ if you added patches or other extra files
+git add pkg/
+git commit
+```
+
+Complete the commit message in the editor, then move to the next package if you have one and repeat. Each package is a separate `git add` / `git commit` cycle.
+
+<Aside type="tip" title="Stage only the current recipe">
+  Stay inside the package directory and add paths relative to it. That avoids accidentally staging unrelated work from another recipe on the same branch.
+</Aside>
+
+
+## Amending an existing package commit
+
+To change a package you have already committed on this branch — review feedback, a missed file, or a rebuild — stay in that recipe directory and run `fixup-recipe-commit`. It is only for amending an existing package commit. Create the first commit with `git add` and `git commit`.
+
+```bash
+chpkg nano
+# make the additional edits and rebuild if the recipe changed
+fixup-recipe-commit
+```
+
+The helper (bash and zsh, after [Prerequisites](/packaging/workflow/prerequisites/)) stages the recipe files, fixups the last commit that touched this directory, and autosquashes it. If you have already pushed the branch:
+
+```bash
+git push --force-with-lease
+```
+
+<Aside type="caution">
+  Do not run this unless the package already has a commit on your branch. Without one, it can fixup an unrelated older commit that last touched the directory.
+</Aside>
+
+
+## Common git commands
+
+These are the commands we use most often while packaging. Pair them with the helper functions from [Prerequisites](/packaging/workflow/prerequisites/) (`gotoaosrepo`, `chpkg`) and the branch setup in [Preparing for packaging](/packaging/workflow/preparing-for-packaging/).
+
+### Moving around and inspecting
+
+| Command | What it does |
+|---------|----------------|
+| `gotoaosrepo` | Jump to the recipes repository root. |
+| `chpkg <name>` | Jump to that package's recipe directory. |
+| `git status` | Show staged, unstaged, and untracked files. |
+| `git diff` | Show unstaged changes. |
+| `git diff --staged` | Show staged changes that will go into the next commit. |
+| `git log --oneline` | Show recent commits. |
+| `git log -1 -- .` | Show the latest commit that touched the current directory. |
+| `git branch -a` | List local and remote branches. |
+
+### Updating `main` and creating a branch
+
+```bash
+gotoaosrepo
+git switch main
+gh repo sync yourusername/yourfork -b main
+git pull
+git switch -c update-nano
+```
+
+Use `add-packagename` or `update-packagename` as the branch name. See [Preparing for packaging](/packaging/workflow/preparing-for-packaging/) for the full recap.
+
+### Committing and sharing
+
+| Command | What it does |
+|---------|----------------|
+| `git add <files>` | Stage recipe files for the current package. |
+| `git commit` | Create a commit. The `prepare-commit-msg` hook prefills the title. |
+| `git push -u origin HEAD` | Publish the current branch to your fork. |
+| `git push --force-with-lease` | Update a branch you have already pushed after a rebase. |
+| `git gone` | Delete local branches whose upstream branch no longer exists. Set this alias up in [Prerequisites](/packaging/workflow/prerequisites/). |
+
+Once the branch is on your fork, open the pull request on GitHub. [Submitting a PR](/packaging/workflow/submitting-a-pr/) covers commit message format and pull request descriptions.
+
+
+## Handling review feedback
+
+Stay on the pull request branch, change the package that was requested, and [amend that package's existing commit](#amending-an-existing-package-commit). Do not add a second commit for the same package.