diff --git a/README.md b/README.md index 4a06969d6..983c6e8fe 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,90 @@ # Twoliter -A build tool for creating [Bottlerocket] variants. +A build tool for creating custom [Bottlerocket] variants. [Bottlerocket]: https://github.com/bottlerocket-os/bottlerocket -## 🚧👷 +## Status 🚧👷 -This project is just getting started and is not ready for contributions. -Soon we will be posting a design document and creating GitHub issues. +This project is a work in progress and is not ready for outside contributors yet. +Issues marked as "good first issue" are intended for team members at this time. +There is a design doc describing how Twoliter is intended to be built, [here] We welcome ideas and requirements in the form of issues and comments! +[here]: docs/design/README.md + ## For Maintainers This section includes information for maintainers about testing and releasing Twoliter. -### Release +## Testing + +In general, if you have changes to Twoliter and want to try them out in a Twoliter project, it is as simple as building the Twoliter binary and using it in your project. +Different projects will have different ways of making sure the correct Twoliter binary is being used. +For example, Bottlerocket has a script and Makefile.toml variables that ensure the correct version of Twoliter is being used to build Bottlerocket. +The following sections describe how to use those mechanisms to use a non-released version of Twoliter. + +### Testing Twoliter Changes in the Bottlerocket Repo + +The process of testing changes to Twoliter in Bottlerocket is as follows: +- Commit your changes. This can be either a local commit or a commit on a git fork. +- In the Bottlerocket git repo + - Remove the existing Twoliter binary if it exists. + - Run any/all `cargo make` commands with the following environment + variables. + +```sh +# The URL to the Twoliter git repository. This can be anything that git remote add would accept. +# Here we are using a path on the local filesystem. +TWOLITER_REPO=file:///home/myuser/repos/twoliter +# The sha of the commit you want to use. Make sure changes have been committed! +TWOLITER_VERSION=a8b30def +# These need to be set as follows. +TWOLITER_ALLOW_SOURCE_INSTALL=true +TWOLITER_ALLOW_BINARY_INSTALL=false +TWOLITER_SKIP_VERSION_CHECK=true +``` + +So, for example, to build a Bottlerocket image using a commit on a fork, I would look like this: + +```sh + rm -rf tools/twoliter + cargo make -e=TWOLITER_REPO=https://github.com/webern/twoliter \ + -e=TWOLITER_VERSION=11afef09 \ + -e=TWOLITER_ALLOW_SOURCE_INSTALL=true \ + -e=TWOLITER_ALLOW_BINARY_INSTALL=false \ + -e=TWOLITER_SKIP_VERSION_CHECK=true \ + build-variant +``` + +### Alternative Method of Testing in the Bottlerocket Repo + +Another way you can test your Twoliter changes in the Bottlerocket repo is by building twoliter and +moving it into the right place, then telling `cargo make` not to install Twoliter at all. + +For example, if you have set `TWOLITER_REPO` and `BOTTLEROCKET_REPO` to the respective local git repositories, then: + +```shell +cd $TWOLITER_REPO +cargo build --release --package twoliter --bin twoliter +rm -rf $BOTTLEROCKET_REPO/tools/twoliter +mkdir -p $BOTTLEROCKET_REPO/tools/twoliter +cp $TWOLITER_REPO/target/release/twoliter $BOTTLEROCKET_REPO/tools/twoliter + +cd $BOTTLEROCKET_REPO + +cargo make \ + -e=TWOLITER_ALLOW_SOURCE_INSTALL=false \ + -e=TWOLITER_ALLOW_BINARY_INSTALL=false \ + -e=TWOLITER_SKIP_VERSION_CHECK=true \ + build-variant +``` + +## Releasing A release consists of a semver tag in the form `v0.0.0`. We also use release-candidate tags in the form `v0.0.0-rc1`. -Release-candidate tags are typically deleted after the release is done. We use a fork of `cargo-dist` to facilitate binary releases. The purpose of the `cargo-dist` fork is to enable cross-compilation with `cross` @@ -31,6 +96,8 @@ To perform a release: - Push a release-candidate tag, e.g. `v0.0.4-rc1`. - That will kick of a GitHub Actions workflow that creates a GitHub release and attaches binaries. - Create a Bottlerocket PR ([example]) that uses the new version of Twoliter. + At first, your PR will use the candidate tag. + Before merging, you will use the final release tag. - Test Twoliter in Bottlerocket - `cargo make` - `cargo make ami`