From 856a73fa9857803a3b258778a3f7f4fd71ea7620 Mon Sep 17 00:00:00 2001
From: Paul Campbell <pcampbell@kemitix.net>
Date: Sat, 6 Apr 2024 17:52:23 +0100
Subject: [PATCH] docs(readme): Add initial notes

---
 README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index e316645f..25790244 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,63 @@
 # git-next
 
-Automated and minimal merge-queue ideal for a solo developer (later versions may support teams)
\ No newline at end of file
+Automated and minimal merge-queue ideal for a solo developer (later versions may support teams)
+
+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.
+
+The `main` branch remains the ready-to-deploy version of the project.
+
+I would then have a `dev` branch where I would do all of my work.
+
+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.
+
+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.
+
+### Design
+
+- CLI to initialise the Repo (e.g. create config file)
+- 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.