diff --git a/docs/abra/hack.md b/docs/abra/hack.md new file mode 100644 index 0000000..ec25629 --- /dev/null +++ b/docs/abra/hack.md @@ -0,0 +1,47 @@ +--- +title: Hack +--- + +## Quick start + +Get a fresh copy of the `abra` source code from [here](https://git.coopcloud.tech/coop-cloud/abra). + +Install [direnv](https://direnv.net), run `cp .envrc.sample .envrc`, then run `direnv allow` in this directory. This will set coopcloud repos as private due to [this bug.](https://git.coopcloud.tech/coop-cloud/coopcloud.tech/issues/20#issuecomment-8201). Or you can run `go env -w GOPRIVATE=coopcloud.tech` but I'm not sure how persistent this is. + +Install [Go >= 1.16](https://golang.org/doc/install) and then: + +- `make build` to build +- `./abra` to run commands +- `make test` will run tests +- `make install` will install it to `$GOPATH/bin` +- `go get ` and `go mod tidy` to add a new dependency + +Our [Drone CI configuration](.drone.yml) runs a number of sanity on each pushed commit. See the [Makefile](./Makefile) for more handy targets. + +Please use the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/) for your commits so we can automate our change log. + +## Release management + +We use [goreleaser](https://goreleaser.com) to help us automate releases. We use [semver](https://semver.org) for versioning all releases of the tool. While we are still in the public alpha release phase, we will maintain a `0.y.z-alpha` format. Change logs are generated from our commit logs. We are still working this out and aim to refine our release praxis as we go. + +For developers, while using this `-alpha` format, the `y` part is the "major" version part. So, if you make breaking changes, you increment that and _not_ the `x` part. So, if you're on `0.1.0-alpha`, then you'd go to `0.1.1-alpha` for a backwards compatible change and `0.2.0-alpha` for a backwards incompatible change. + +### Making a new release + +- Change `ABRA_VERSION` to match the new tag in [`scripts`](./scripts/installer/installer) (use [semver](https://semver.org)) +- Commit that change (e.g. `git commit -m 'chore: publish next tag x.y.z-alpha'`) +- Make a new tag (e.g. `git tag -a x.y.z-alpha`) +- Push the new tag (e.g. `git push && git push --tags`) +- Wait until the build finishes on [build.coopcloud.tech](https://build.coopcloud.tech/coop-cloud/abra) +- Deploy the new installer script (e.g. `cd ./scripts/installer && make`) +- Check the release worked, (e.g. `abra upgrade; abra -v`) + +## Fork maintenance + +### `godotenv` + +We maintain a fork of [godotenv](https://github.com/Autonomic-Cooperative/godotenv) because we need inline comment parsing for environment files. You can upgrade the version here by running `go get github.com/Autonomic-Cooperative/godotenv@` where `` is the latest commit you want to pin to. At time of writing, `go get github.com/Autonomic-Cooperative/godotenv@b031ea1211e7fd297af4c7747ffb562ebe00cd33` is the command you want to run to maintain the above functionality. + +### `docker/client` + +A number of modules in [pkg/upstream](./pkg/upstream) are copy/pasta'd from the upstream [docker/docker/client](https://pkg.go.dev/github.com/docker/docker/client). We had to do this because upstream are not exposing their API as public. diff --git a/docs/abra/index.md b/docs/abra/index.md new file mode 100644 index 0000000..4a44a50 --- /dev/null +++ b/docs/abra/index.md @@ -0,0 +1,12 @@ +--- +title: Abra +--- + +`abra` is our flagship client & command-line tool which has been developed specifically in the context of the Co-op Cloud project for the purpose of making day-to-day operations for [operators](/operators/) and [maintainers](/maintainers/) as convenient as possible. It is libre software, written in [Go](https://go.dev/) and maintained and extended by the community :heart: + +In this section, you can find the following sections: + +- [Install](/abra/install): You want to install `abra` :100: +- [Upgrade](/abra/upgrade): You're looking for instructions on how to upgrade `abra` :arrow_heading_up: +- [Hack](/abra/hack): You wan to hack on `abra` and help out with the development :woman_construction_worker: +- [Troubleshoot](/abra/troubleshoot): `abra` ain't working and you'd like to know why :boom: diff --git a/docs/abra/install.md b/docs/abra/install.md new file mode 100644 index 0000000..073971c --- /dev/null +++ b/docs/abra/install.md @@ -0,0 +1,19 @@ +--- +title: Install +--- + +## Stable release + +``` +curl https://install.abra.coopcloud.tech | bash +``` + +## Release candidate + +``` +curl https://install.abra.coopcloud.tech | bash -s -- --rc +``` + +## Installer script source + +You can view that [here](https://git.coopcloud.tech/coop-cloud/abra/src/branch/main/scripts/installer/installer). diff --git a/docs/operators/trouble.md b/docs/abra/trouble.md similarity index 68% rename from docs/operators/trouble.md rename to docs/abra/trouble.md index d0eb750..a22d7e1 100644 --- a/docs/operators/trouble.md +++ b/docs/abra/trouble.md @@ -1,5 +1,5 @@ --- -title: Troubleshooting +title: Troubleshoot --- ## Configuring SSH diff --git a/docs/abra/upgrade.md b/docs/abra/upgrade.md new file mode 100644 index 0000000..4fcbd3c --- /dev/null +++ b/docs/abra/upgrade.md @@ -0,0 +1,15 @@ +--- +title: Upgrade +--- + +## Stable release + +``` +abra upgrade +``` + +## Release candidate + +``` +abra upgrade --rc +``` diff --git a/mkdocs.yml b/mkdocs.yml index 3d6b0ce..128a372 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,7 +49,6 @@ nav: - operators/index.md - "New operators tutorial": operators/tutorial.md - "Operations handbook": operators/handbook.md - - "Troubleshooting abra": operators/trouble.md - "Maintainers Guide": - maintainers/index.md - "New maintainers tutorial": maintainers/tutorial.md @@ -58,6 +57,12 @@ nav: - "New organisers tutorial": organisers/tutorial.md - "Schedules": organisers/schedules.md - "Recipes": recipes/index.md + - "Abra": + - abra/index.md + - "Install": abra/install.md + - "Upgrade": abra/upgrade.md + - "Hack": abra/hack.md + - "Troubleshoot": abra/trouble.md - "Get Involved": get-involved/index.md - "Glossary": glossary/index.md