forked from kemitix/git-next
docs(readme): add msrv and some formatting
This commit is contained in:
parent
2cefe07a80
commit
e3205af094
1 changed files with 35 additions and 18 deletions
53
README.md
53
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
|
||||
|
||||
|
|
Loading…
Reference in a new issue