docs(readme): rewrite README

This commit is contained in:
Paul Campbell 2024-04-12 11:25:53 +01:00
parent be3aded382
commit 53f66d5ee5

View file

@ -21,7 +21,7 @@ cargo install git-next
## Configuration ## Configuration
- The repo has a `.git-next.toml` file in it's root. (N.B. see [#28](kemitix/git-next#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`. - 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 `dev` branch _must_ have the `main` branch as an ancestor.
- The `next` branch _must_ have the `main` branch as an ancestor. - The `next` branch _must_ have the `main` branch as an ancestor.
@ -30,13 +30,73 @@ cargo install git-next
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)
```mermaid
gitGraph
commit
commit
branch next
branch dev
commit
commit
commit
```
When the `git-next` server sees that the `dev` branch is ahead of the `next` branch, it will push the `next` 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. fast-forward one commit along the `dev` branch.
```mermaid
gitGraph
commit
commit
branch next
commit
branch dev
commit
commit
```
It will then wait for the CI checks to pass for the newly updated `next` 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. When the CI checks for the `next` branch pass, it will push the `main` branch fast-forward to the `next` branch.
```mermaid
gitGraph
commit
commit
commit
branch next
branch dev
commit
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. They should then force-push their rebased `dev` branch.
```mermaid
gitGraph
commit
commit
branch next
commit
checkout main
branch dev
commit
commit
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`. We then return to the top, where `git-next` sees that `dev` is ahead of `next`.
@ -94,10 +154,11 @@ git next server start
## Contributing ## 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. 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 ## License
`git-next` is released under the [MIT License](https://git.kemitix.net/kemitix/git-next/-/blob/main/LICENSE). `git-next` is released under the [MIT License](./LICENSE).