docs(readme): rewrite README

README.md

@@ -1,69 +1,103 @@
 # git-next
 
+`git-next` is a combined server and command-line tool that enables trunk-based development workflows
+where each commit must pass CI before being included in the main branch.
+
 [![status-badge](https://ci.kemitix.net/api/badges/52/status.svg)](https://ci.kemitix.net/repos/52)
 
-Automated and minimal merge-queue ideal for a solo developer (later versions may support teams)
+## Features
 
-Currently this will mostly for myself when working on projects by myself. I'd like to reduce the overhead of PRs, but still maintain CI verification of each commit/patch set.
+- Enforce the requirement for each commit to pass the CI pipeline before being 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 from being merged
 
-The `main` branch remains the ready-to-deploy version of the project.
+## Installation
 
-I would then have a `dev` branch where I would do all of my work.
+You can install `git-next` using Cargo:
 
-As a commit is added, as long as it matches a conventional commit message and isn't marked as `WIP:`, the `next` branch will advance from the current `main` commit to this next commit where it will be submitted to CI. This may or may not involve a PR. If it passes CI then the `main` branch will fast-forward to that commit (i.e. to `next` which should be a single step). The next commit on the `dev` branch will then be considered.
+```shell
-
+cargo install git-next
-The application would initially integrate with only with ForegeJo via it's API to interact with the `main`, `next` and `dev` branches and to review the status check results for each commit or PR.
-
-```
-Before:
-*1--*2--*3--*4--*5 main/next
-                 \--*6--*7--*8--*9 dev
-During CI:
-*1--*2--*3--*4--*5 main
-                 \--*6 next
-                     \--*7--*8--*9 dev
-After CI passes for *6:
-*1--*2--*3--*4--*5--*6 main/next
-                     \--*7--*8--*9 dev
 ```
 
-The `dev` branch should never need to rebase onto `main` as `main` is only ever advancing along the `dev` branch as each commit passes CI.
+## Configuration
 
-### Developing on git-next
+- The repo has a `.git-next.toml` file in it's root. (N.B. see [#28](kemitix/git-next#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 be able to pass the CI checks.
+
+When the `git-next` server sees that the `dev` branch is ahead of the `next` branch, it will push the `next` branch
+fast-forward one commit along the `dev` branch.
+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 fast-forward to the `next` branch.
+
+If the CI checks should fail for the `next` branch, the developer should **amend** that commit in the history of their `dev` branch.
+They should then force-push their rebased `dev` branch.
+`git-next` will then detect that the `next` branch is no longer part of the `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** the `next` branch back to the same commit as the `main` branch.
+
+In short, the `next` branch **belongs** to `git-next`.
+
+## Getting Started
+
+To use `git-next` for trunk-based development, follow these steps:
+
+### Initialise the repo
+
+You need to specify which branches you are using
+
+To create the default config file, run this command in the root of your repo:
+
+```shell
+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 three branches _must_ exist in your repo.
+
+### Initialise the server
+
+The server uses the file `git-next-server.toml` for configuration.
+
+The create the default config file, run this command:
+
+```shell
+git next server init
+```
+
+This will create a `git-next-server.toml` file. [Default](./server-default.toml)
+
+Edit this file to your needs.
+
+Specify the access token.
+
+The `branch` parameter for the repo identies the branch where the `.git-next.toml` file should be found.
+
+### Run the server
+
+In the directory with your `git-next-server.toml` file, run the command:
+
+```shell
+git next server start
+```
+
+## Contributing
+
+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). 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 Git Hooks. [Get Just](https://just.systems/man/en/chapter_3.html)
 
-### Design
+## License
 
-- CLI to initialise the Repo (e.g. create config file)
+`git-next` is released under the [MIT License](https://git.kemitix.net/kemitix/git-next/-/blob/main/LICENSE).
-- Server that monitors a collection of repos via the Forge APIs
-
-The CLI and the Server could be the same executable taking different commands to decide behaviour.
-
-e.g.
-
-(assuming the command is `git-next`)
-
-Initialise a repo:
-
-```
-$ git next init
-```
-
-This would create a default configuration file: `.git-next.toml`.
-
-Initialise a Server:
-
-```
-$ git next server init
-```
-
-This would create a configuration file `git-next-server.toml` for running the server. It would include details of the repos to be monitored and any credentials to be used.
-
-Start a Server:
-
-```
-$ git next server start
-```
-
-This would start a server using the configuration file in the current directory.