README.md

@@ -1,24 +1,13 @@
 # git-next
 
-`git-next` is a combined server and command-line tool that enables trunk-based
+`git-next` is a combined server and command-line tool that enables trunk-based development workflows
-development workflows where each commit must pass CI before being included in
+where each commit must pass CI before being included in the main branch.
-the main branch.
 
 ## Features
 
-- Enforce the requirement for each commit to pass the CI pipeline before being
+- Enforce the requirement for each commit to pass the CI pipeline before being included in the main branch
-  included in the main branch
 - Provide a server component that manages the trunk-based development process
-- Ensure a consistent, high-quality codebase by preventing untested changes
+- Ensure a consistent, high-quality codebase by preventing untested changes from being merged
-  from being merged
-
-## Prerequisits
-
-- Rust 1.76.0 or later
-- pgk-config
-- libssl-dev
-- clang-16
-- mold
 
 ## Installation
 
@@ -30,20 +19,16 @@ cargo install git-next
 
 ## Configuration
 
-- The repo has a `.git-next.toml` file in it's root. (N.B. see
+- The repo has a `.git-next.toml` file in it's root. (N.B. see [#28](https://git.kemitix.net/kemitix/git-next/issues/28) for a planned alternative)
-  [#28](https://git.kemitix.net/kemitix/git-next/issues/28) for a planned
-  alternative)
 - CI checks should be configured to run when the `next` branch is `pushed`.
 - The `dev` branch _must_ have the `main` branch as an ancestor.
 - The `next` branch _must_ have the `main` branch as an ancestor.
 
 ## Behaviour
 
-Development happens on the `dev` branch, where each commit is expected to
+Development happens on the `dev` branch, where each commit is expected to be able to pass the CI checks.
-be able to pass the CI checks.
 
-(Note: in the diagrams, mermaid isn't capable of showing `main` and `next` on
+(Note: in the diagrams, mermaid isn't capable of showing `main` and `next` on the same commit, so we show `next` as empty)
-the same commit, so we show `next` as empty)
 
 ```mermaid
 gitGraph
@@ -58,9 +43,8 @@ gitGraph
     commit
 ```
 
-When the `git-next` server sees that the `dev` branch is ahead of the `next`
+When the `git-next` server sees that the `dev` branch is ahead of the `next` branch, it will push the `next` branch
-branch, it will push the `next` branch fast-forward one commit along the `dev`
+fast-forward one commit along the `dev` branch.
-branch.
 
 ```mermaid
 gitGraph
@@ -76,8 +60,7 @@ gitGraph
 ```
 
 It will then wait for the CI checks to pass for the newly updated `next` branch.
-When the CI checks for the `next` branch pass, it will push the `main` branch
+When the CI checks for the `next` branch pass, it will push the `main` branch fast-forward to the `next` branch.
-fast-forward to the `next` branch.
 
 ```mermaid
 gitGraph
@@ -92,8 +75,7 @@ gitGraph
     commit
 ```
 
-If the CI checks should fail for the `next` branch, the developer should
+If the CI checks should fail for the `next` branch, the developer should **amend** that commit in the history of their `dev` branch.
-**amend** that commit in the history of their `dev` branch.
 They should then force-push their rebased `dev` branch.
 
 ```mermaid
@@ -113,16 +95,14 @@ gitGraph
     commit
 ```
 
-`git-next` will then detect that the `next` branch is no longer part of the
+`git-next` will then detect that the `next` branch is no longer part of the `dev` branch ancestory, and reset `next` back to `main`.
-`dev` branch ancestory, and reset `next` back to `main`.
 We then return to the top, where `git-next` sees that `dev` is ahead of `next`.
 
 ### Important
 
 The `dev` branch _should_ have the `next` branch as an ancestor.
 
-If the `git-next` server finds that this isn't the case, it will **force-push**
+If the `git-next` server finds that this isn't the case, it will **force-push** the `next` branch back to the same commit as the `main` branch.
-the `next` branch back to the same commit as the `main` branch.
 
 In short, the `next` branch **belongs** to `git-next`.
 
@@ -142,8 +122,7 @@ git next init
 
 This will create a `.git-next.toml` file. [Default](./default.toml)
 
-By default the expected branches are `main`, `next` and `dev`. Each of these
+By default the expected branches are `main`, `next` and `dev`. Each of these three branches _must_ exist in your repo.
-three branches _must_ exist in your repo.
 
 ### Initialise the server
 
@@ -161,8 +140,7 @@ Edit this file to your needs.
 
 Specify the access token.
 
-The `branch` parameter for the repo identies the branch where the
+The `branch` parameter for the repo identies the branch where the `.git-next.toml` file should be found.
-`.git-next.toml` file should be found.
 
 ### Run the server
 
@@ -174,13 +152,10 @@ git next server start
 
 ## Contributing
 
-Contributions to `git-next` are welcome! If you find a bug or have a feature
+Contributions to `git-next` are welcome! If you find a bug or have a feature request, please [create an issue](https://git.kemitix.net/kemitix/git-next/issues/new).
-request, please
-[create an issue](https://git.kemitix.net/kemitix/git-next/issues/new).
 If you'd like to contribute code, feel free to submit a merge request.
 
-Before you start committing, run the `just install-hooks` command to setup the
+Before you start committing, run the `just install-hooks` command to setup the Git Hooks. ([Get Just](https://just.systems/man/en/chapter_3.html))
-Git Hooks. ([Get Just](https://just.systems/man/en/chapter_3.html))
 
 ## License