git-next/README.md

214 lines
4.6 KiB
Markdown
Raw Normal View History

2024-04-06 17:31:05 +01:00
# 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.
2024-04-12 11:03:32 +01:00
## Features
2024-04-06 17:52:23 +01:00
- Enforce the requirement for each commit to pass the CI pipeline before being
included in the main branch
2024-04-12 11:03:32 +01:00
- Provide a server component that manages the trunk-based development process
- Ensure a consistent, high-quality codebase by preventing untested changes
from being merged
2024-04-06 17:52:23 +01:00
2024-05-17 18:32:55 +01:00
## Prerequisits
- Rust 1.76.0 or later
2024-05-17 18:32:55 +01:00
- pgk-config
- libssl-dev
- clang-16
- mold
2024-04-12 11:03:32 +01:00
## Installation
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
You can install `git-next` using Cargo:
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
```shell
cargo install git-next
```
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
## Configuration
2024-04-06 17:52:23 +01:00
- 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)
2024-04-12 11:03:32 +01:00
- 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.
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
## Behaviour
2024-04-06 17:52:23 +01:00
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)
2024-04-12 11:25:53 +01:00
```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 fast-forward one commit along the `dev`
branch.
2024-04-12 11:25:53 +01:00
```mermaid
gitGraph
commit
commit
branch next
commit
branch dev
commit
commit
```
2024-04-12 11:03:32 +01:00
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.
2024-04-12 11:25:53 +01:00
```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.
2024-04-12 11:03:32 +01:00
They should then force-push their rebased `dev` branch.
2024-04-12 11:25:53 +01:00
```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`.
2024-04-12 11:03:32 +01:00
We then return to the top, where `git-next` sees that `dev` is ahead of `next`.
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
### Important
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
The `dev` branch _should_ have the `next` branch as an ancestor.
2024-04-06 17:52:23 +01:00
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.
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
In short, the `next` branch **belongs** to `git-next`.
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
## Getting Started
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
To use `git-next` for trunk-based development, follow these steps:
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
### Initialise the repo
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
You need to specify which branches you are using
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
To create the default config file, run this command in the root of your repo:
```shell
git next init
2024-04-06 17:52:23 +01:00
```
2024-04-12 11:03:32 +01:00
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.
2024-04-12 11:03:32 +01:00
### Initialise the server
The server uses the file `git-next-server.toml` for configuration.
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
The create the default config file, run this command:
2024-04-06 17:52:23 +01:00
2024-04-12 11:03:32 +01:00
```shell
git next server init
2024-04-06 17:52:23 +01:00
```
2024-04-12 11:03:32 +01:00
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.
2024-04-12 11:03:32 +01:00
### Run the server
In the directory with your `git-next-server.toml` file, run the command:
```shell
git next server start
2024-04-06 17:52:23 +01:00
```
2024-04-12 11:03:32 +01:00
## 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).
2024-04-12 11:25:53 +01:00
If you'd like to contribute code, feel free to submit a merge request.
2024-04-12 11:03:32 +01:00
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))
2024-04-12 11:03:32 +01:00
## Crate Dependency
The following diagram shows the dependency between the crates that make up `git-next`:
```mermaid
stateDiagram-v2
cli --> server
cli --> git
server --> config
server --> git
server --> gitforge
server --> repo_actor
git --> config
gitforge --> config
gitforge --> git
repo_actor --> config
repo_actor --> git
repo_actor --> gitforge
```
2024-04-12 11:03:32 +01:00
## License
2024-04-12 11:25:53 +01:00
`git-next` is released under the [MIT License](./LICENSE).