diff --git a/README.md b/README.md index dc884da8..d5d1078a 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,20 @@ # 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. +`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. ## Features -- Enforce the requirement for each commit to pass the CI pipeline before being included in the main branch +- 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 +- Ensure a consistent, high-quality codebase by preventing untested changes + from being merged ## Prerequisits -- Rust ??? +- Rust 1.76.0 or later - pgk-config - libssl-dev - clang-16 @@ -27,16 +30,20 @@ cargo install git-next ## Configuration -- 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) +- 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) - 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. +Development happens on the `dev` branch, where each commit is expected to +be able to pass the CI checks. -(Note: in the diagrams, mermaid isn't capable of showing `main` and `next` on the same commit, so we show `next` as empty) +(Note: in the diagrams, mermaid isn't capable of showing `main` and `next` on +the same commit, so we show `next` as empty) ```mermaid gitGraph @@ -51,8 +58,9 @@ gitGraph commit ``` -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. +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. ```mermaid gitGraph @@ -68,7 +76,8 @@ 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 fast-forward to the `next` branch. +When the CI checks for the `next` branch pass, it will push the `main` branch +fast-forward to the `next` branch. ```mermaid gitGraph @@ -83,7 +92,8 @@ gitGraph commit ``` -If the CI checks should fail for the `next` branch, the developer should **amend** that commit in the history of their `dev` 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. ```mermaid @@ -103,14 +113,16 @@ gitGraph commit ``` -`git-next` will then detect that the `next` branch is no longer part of the `dev` branch ancestory, and reset `next` back to `main`. +`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. +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`. @@ -130,7 +142,8 @@ 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. +By default the expected branches are `main`, `next` and `dev`. Each of these +three branches _must_ exist in your repo. ### Initialise the server @@ -148,7 +161,8 @@ 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. +The `branch` parameter for the repo identies the branch where the +`.git-next.toml` file should be found. ### Run the server @@ -160,10 +174,13 @@ 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). +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)) +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)) ## License