docs(readme): flesh out and update README
This commit is contained in:
parent
044790a019
commit
16f98daa86
2 changed files with 172 additions and 23 deletions
193
README.md
193
README.md
|
@ -1,5 +1,7 @@
|
|||
# git-next
|
||||
|
||||
- Status: Alpha - dog-fooding
|
||||
|
||||
`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.
|
||||
|
@ -14,12 +16,19 @@ the main branch.
|
|||
|
||||
## Prerequisits
|
||||
|
||||
- Rust 1.76.0 or later
|
||||
- Rust 1.76.0 or later - https://www.rust-lang.org
|
||||
- pgk-config
|
||||
- libssl-dev
|
||||
|
||||
### x86_64-unknown-linux-gnu
|
||||
|
||||
Additionally for this platform, to improved compilation times:
|
||||
|
||||
- clang-16
|
||||
- mold
|
||||
|
||||
See `.cargo/config.toml` for how they are configured.
|
||||
|
||||
## Installation
|
||||
|
||||
You can install `git-next` using Cargo:
|
||||
|
@ -28,15 +37,141 @@ You can install `git-next` using Cargo:
|
|||
cargo install --path .
|
||||
```
|
||||
|
||||
Not yet available to install from `crates.io`.
|
||||
|
||||
## Branch Names
|
||||
|
||||
`git-next` uses three branches, `main`, `next` and `dev`, although they do not
|
||||
need to have those names. In the documentation we will use those names, but
|
||||
each repo must specify the names of the branches to use for each, even if they
|
||||
happen to have those same names.
|
||||
|
||||
## 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 branches to use for `main`, `next` and `dev` must be specified in either
|
||||
the `.git-next.toml` in the repo itself, or in the server configuration file,
|
||||
`git-next-server.toml`. See below for details.
|
||||
- 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.
|
||||
|
||||
### Server
|
||||
|
||||
#### http
|
||||
|
||||
The server needs to be able to receive webhook notifications from your forge,
|
||||
(e.g. github.com). You can do this via any method that suits your environment,
|
||||
e.g. ngrok or a reverse proxy from a web server that itself can route traffic
|
||||
to the machine you are running the git-next server on.
|
||||
|
||||
Specify the address and port the server should listen to for incoming webhooks.
|
||||
This is the address and port that your reverse proxy should route traffic to.
|
||||
|
||||
- **addr** - the IP address the server should bind to
|
||||
- **port** - the IP port the server should bind to
|
||||
|
||||
#### webhook
|
||||
|
||||
Your forges need to know where they should route webhooks to. This should be
|
||||
an address this is accessible to the forge. So, for github.com, it would need
|
||||
to be a publicly accessible HTTPS URL. For a self-hosted forge, e.g. ForgeJo,
|
||||
on your own network, then it only needs to be accessible from the server your
|
||||
forge is running on.
|
||||
|
||||
- **url** - the HTTPS URL for forges to send webhook to
|
||||
|
||||
#### storage
|
||||
|
||||
`git-next` will create a bare clone of each repo that you configure it to
|
||||
monitor. They will all be created in the directory specified here. This data
|
||||
does not need to be backed up, as any missing information will be cloned when
|
||||
the server starts up.
|
||||
|
||||
- **path** - directory to store local copies of monitored repos
|
||||
|
||||
#### forge
|
||||
|
||||
Within the forge tree, specify each forge you want to monitore repos on.
|
||||
|
||||
Give your forge an alias, e.g. `default`, `gh`, `github`.
|
||||
|
||||
e.g.
|
||||
|
||||
```toml
|
||||
[forge.github]
|
||||
forge_type = "GitHub"
|
||||
hostname = "github.com"
|
||||
user = "username"
|
||||
token = "api-key"
|
||||
```
|
||||
|
||||
- **forge_type** - one of: `ForgeJo` or `GitHub`
|
||||
- **hostname** - the hostname for the forge.
|
||||
- **user** - the user to authenticate as
|
||||
- **token** - application token for the user. See below for the permissions
|
||||
required for on each forge.
|
||||
|
||||
Generally, the `user` will need to be able to push to `main` and to _force-push_
|
||||
to `next`.
|
||||
|
||||
#### repos
|
||||
|
||||
For each forge, you need to specify which repos on the forge you want to
|
||||
monitor. They do not need to be owned by the `user`, but they `user` must have
|
||||
the `push` and `force-push` permissions as mentioned above for each of the
|
||||
repositories.
|
||||
|
||||
e.g.
|
||||
|
||||
```toml
|
||||
[forge.github.repos]
|
||||
my-repo = { repo = "owner/repo", branch = "main", gitdir = "/home/pcampbell/project/my-repo" }
|
||||
|
||||
[forge.github.repos.other-repo]
|
||||
repo = "user/other"
|
||||
branch = "master"
|
||||
main = "master"
|
||||
next = "ci-testing"
|
||||
dev = "trunk"
|
||||
```
|
||||
|
||||
Note that toml allows specifying the values on one line, or across multiple
|
||||
lines. Both are equivalent. What is not equivalent between `my-repo` and
|
||||
`other-repo`, is that one will require a configuration file within the repo
|
||||
itself. `other-repo` specifies the `main`, `next` and `dev` branches to be
|
||||
used, but `my-repo` doesn't.
|
||||
|
||||
A sample `.git-next-toml` file that would need to exist in the `user/other`
|
||||
repo, on the `main` branch:
|
||||
|
||||
```toml
|
||||
[branches]
|
||||
main = "main"
|
||||
next = "next"
|
||||
dev = "dev"
|
||||
```
|
||||
|
||||
- **repo** - the owner and name of the repo to be monitored
|
||||
- **branch** - the branch to look for a `.git-next.toml` file is needed
|
||||
- **gitdir** - (optional) you can use local copy of the repo
|
||||
- **main** - the branch to use as `main`
|
||||
- **next** - the branch to use as `next`
|
||||
- **dev** - the branch to use as `dev`
|
||||
|
||||
##### gitdir
|
||||
|
||||
Additional notes on using `gitdir`:
|
||||
|
||||
When you specify the `gitdir` value, the repo will be used for perform the
|
||||
equivalent of `git fetch`, `git push` and `git push --force-with-lease`.
|
||||
|
||||
These commands will not affect the contents of your working tree, not will
|
||||
it change any local branches. Only the details about branches on the remote
|
||||
forge will be updated.
|
||||
|
||||
Currently `git-next` can only use a `gitdir` if the forge is the same one
|
||||
specified as `origin`. Otherwise the behaviour is untested/undefined.
|
||||
|
||||
## Behaviour
|
||||
|
||||
Development happens on the `dev` branch, where each commit is expected to
|
||||
|
@ -77,7 +212,7 @@ 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.
|
||||
fast-forward to the `next` branch. We return to the top and start again.
|
||||
|
||||
```mermaid
|
||||
gitGraph
|
||||
|
@ -93,7 +228,7 @@ gitGraph
|
|||
```
|
||||
|
||||
If the CI checks should fail for the `next` branch, the developer should
|
||||
**amend** that commit in the history of their `dev` branch.
|
||||
**amend** that commit **in the history of their `dev` branch**.
|
||||
They should then force-push their rebased `dev` branch.
|
||||
|
||||
```mermaid
|
||||
|
@ -114,27 +249,38 @@ gitGraph
|
|||
```
|
||||
|
||||
`git-next` will then detect that the `next` branch is no longer part of the
|
||||
`dev` branch ancestory, and reset `next` back to `main`.
|
||||
`dev` branch ancestory, and will reset `next` back to `main`.
|
||||
We then return to the top, where `git-next` sees that `dev` is ahead of `next`.
|
||||
|
||||
When the `dev` branch is on the same commit as the `main` branch, then there
|
||||
are no pending commits and `git-next` will wait until it receives a webhook
|
||||
indicating that there has been a push to one of the branches. At which point
|
||||
it will start at the top again.
|
||||
|
||||
### 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.
|
||||
However, when the commit on tip of the `next` branch has failed CI and is
|
||||
amended, this will not be the case. When this happens `git-next` will
|
||||
**force-push** the `next` branch back to the same commit as the `main` branch.
|
||||
|
||||
In short, the `next` branch **belongs** to `git-next`.
|
||||
This is the only time a force-push will happen in `git-next`.
|
||||
|
||||
In short, the `next` branch **belongs** to `git-next`. Don't try to update it
|
||||
yourself. `git-next` will update the `next` it as it sees fit.
|
||||
|
||||
## Getting Started
|
||||
|
||||
To use `git-next` for trunk-based development, follow these steps:
|
||||
|
||||
### Initialise the repo
|
||||
### Initialise the repo (optional)
|
||||
|
||||
You need to specify which branches you are using
|
||||
You need to specify which branches you are using. You can do this in the repo,
|
||||
or in the server configuration.
|
||||
|
||||
To create the default config file, run this command in the root of your repo:
|
||||
To create a default config file for the repo, run this command in the root of
|
||||
your repo:
|
||||
|
||||
```shell
|
||||
git next init
|
||||
|
@ -147,7 +293,8 @@ three branches _must_ exist in your repo.
|
|||
|
||||
### Initialise the server
|
||||
|
||||
The server uses the file `git-next-server.toml` for configuration.
|
||||
The server uses the file `git-next-server.toml` for configuration. It expects
|
||||
to find this file the the current directory when executed.
|
||||
|
||||
The create the default config file, run this command:
|
||||
|
||||
|
@ -157,12 +304,7 @@ git next server init
|
|||
|
||||
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.
|
||||
Edit this file to your needs. See the [Configuration](#configuration) section above.
|
||||
|
||||
### Run the server
|
||||
|
||||
|
@ -174,7 +316,10 @@ git next server start
|
|||
|
||||
### Forges
|
||||
|
||||
The following forges are supported: [ForgeJo](https://forgejo.org) and [GitHub](https://github.com/).
|
||||
The following forges are supported:
|
||||
|
||||
- [ForgeJo](https://forgejo.org)
|
||||
- [GitHub](https://github.com/)
|
||||
|
||||
#### ForgeJo
|
||||
|
||||
|
@ -192,7 +337,9 @@ hello = { repo = "user/hello", branch = "main", gitdir = "/opt/git/projects/user
|
|||
world = { repo = "user/world", branch = "master", main = "master", next = "upcoming", "dev" = "develop" } # maps to the 'master' branch
|
||||
```
|
||||
|
||||
The token is created `/user/settings/applications` and requires the `write:repository` permission.
|
||||
The token is created on your ForgeJo instance at (for example)
|
||||
`https://git.myforgejo.com/user/settings/applications`
|
||||
and requires the `write:repository` permission.
|
||||
|
||||
#### GitHub
|
||||
|
||||
|
@ -217,7 +364,7 @@ The token is created [here](https://github.com/settings/tokens/new) and requires
|
|||
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.
|
||||
If you'd like to contribute code, feel free to submit changes.
|
||||
|
||||
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))
|
||||
|
|
|
@ -8,6 +8,8 @@ url = "https://localhost:8080"
|
|||
[storage]
|
||||
path = "./data"
|
||||
|
||||
[forge]
|
||||
|
||||
[forge.default]
|
||||
forge_type = "ForgeJo"
|
||||
hostname = "git.example.net"
|
||||
|
|
Loading…
Reference in a new issue