diff --git a/docs/Contributing/Release.md b/docs/Contributing/Release.md new file mode 100644 index 000000000..1b3589465 --- /dev/null +++ b/docs/Contributing/Release.md @@ -0,0 +1,244 @@ +# Release Process + +## Prerequisites: +- Prepare release notes + + +## Weekly chores +* [Update Rust toolchain](https://github.com/enarx/enarx/actions/workflows/rust-toolchain-update.yml) +* [Update Cargo dependencies](https://github.com/enarx/enarx/actions/workflows/cargo-update.yml) + + +## Enarx Release +> **NOTE:** Regarding git remotes: +> * `upstream` points to core repository location +> * `origin` points to the user's fork + +### Update and release prerequiste crates +> **NOTE:** The list of crates that need to be updated for a release can be seen by running this following command: +> ```bash +> grep -R 'git+https' *.lock | sort | uniq +> ``` +> This may be an optional step dependant on whether there are relevant changes in the prerequisite crates, including: +> * crt0stack +> * flagset +> * iocuddle +> * lset +> * mmarinus +> * mmledger +> * nbytes +> * noted +> * primordial +> * rcrt1 +> * sallyport +> * sgx +> * snp +> * vsdo +> * xsave + +#### Assumptions: +- All approved PRs are merged +- Rust toolchain (if using snapshot) and `cargo update` has been run + +- Determine expected version by reviewing output of `git log` +- Set new version + ```bash + export MAJOR=0 + export MINOR=2 + export PATCH=2 + export NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}" + ``` +- Set REPO variable, assuming GitHub repository matches directory name + ```bash + export REPO="$(basename $PWD)" + ``` +- Get latest updates and checkout branch + > **NOTE:** The following assumes a new release + ```bash + git fetch upstream + git checkout -b "b${MAJOR}.${MINOR}.z" upstream/main + ``` +- Determine if crate builds and if it works + ```bash + cargo clean + cargo build + cargo test + ``` +- Update version in `Cargo.toml` + ```bash + sed -i 's/^version = .*/version = \"'${NEW_VERSION}'\"/' Cargo.toml + cargo update -p $(grep name Cargo.toml | cut -d'"' -f2) + ``` +- Run `cargo test` again + ```bash + cargo clean + cargo build + cargo test + ``` +- Commit change and push to repo + ```bash + git commit -asS -m "chore(release): Release v${NEW_VERSION}" + git push origin b${MAJOR}.${MINOR}.z + ``` +- Create a git tag + ```bash + git tag --sign -m "chore(release): Release v${NEW_VERSION}" v${NEW_VERSION} + git push --tags origin "b${MAJOR}.${MINOR}.z" + ``` +- Create a PR + ```bash + gh pr create -t "chore(release): Release v${NEW_VERSION}" \ + -b "chore(release): Release v${NEW_VERSION}" \ + -B "b${MAJOR}.${MINOR}.z" \ + -R enarx/${REPO} + ``` +- Confirm that changes passed on CI and merge PR +- Checkout merged release branch + ```bash + git fetch --all + git branch -u upstream/"b${MAJOR}.${MINOR}.z" + git reset --hard upstream/"b${MAJOR}.${MINOR}.z" + ``` +- Tag the new release on upstream + ```bash + git tag --sign -m "chore(release): Release v${NEW_VERSION}" v${NEW_VERSION} + git push --tags upstream "b${MAJOR}.${MINOR}.z" + ``` +- Cargo publish + > **NOTE: ** Assuming cargo credentials are cached + ```bash + cargo publish -v + ``` +- Create a release PR + ```bash + gh pr create -t "Release v${NEW_VERSION}" \ + -b "" + -B main \ + -R enarx/${REPO} + ``` +- Merge release PR +- Create draft GitHub release + ```bash + gh release create "v${NEW_VERSION}" + ``` + +### The Enarx release itself +- Determine expected version by reviewing output of `git log` +- Set new version + ```bash + export MAJOR=0 + export MINOR=2 + export PATCH=2 + export NEW_VERSION="${MAJOR}.${MINOR}.${PATCH}" + ``` +- Set REPO variable, assuming GitHub repository matches directory name + ```bash + export REPO="enarx" + ``` +- Get latest updates and checkout branch + ```bash + git fetch upstream + git checkout -b "b${MAJOR}.${MINOR}.z" upstream/main + ``` +- Bump version inside sub-crate `src/bin/{shim-kvm,shim-sgx,exec-wasmtime}/Cargo.toml` files + ```bash + for d in src/bin/*/ ; do ( cd "$d" + sed -i 's/^version = .*/version = \"'${NEW_VERSION}'\"/' Cargo.toml + cargo update -p $(basename ${d}) + done + sed -i 's/^version = .*/version = \"'${NEW_VERSION}'\"/' Cargo.toml + cargo update -p $(grep name Cargo.toml | cut -d'"' -f2) + ``` +- _POTENTIALLY OPTIONAL STEP: If there are any changes in the prerequisite crates (e.g. `xsave`, `sallyport`, etc) then it will be required to manually update the crates now_ + ```bash + export UPDATED_PREREQUISTES=(xsave sallyport) + for d in src/bin/*/ ; do ( cd "$d" + for p in ${UPDATED_PREREQUISTES[@]]}; do + cargo update -p "${p}" + done + done + for p in ${UPDATED_PREREQUISTES[@]]}; do cargo update -p ${p}; done + ``` +- Run unit tests + ```bash + cargo clean + cargo build + cargo test + ``` +- Check cargo manifest + ```bash + cargo package --allow-dirty -l + ``` +- Commit change and push to repo + ```bash + git commit -asS -m "chore(release): Release v${NEW_VERSION}" + git push origin "release/${NEW_VERSION}" + ``` +- Create and push `git` tag + ```bash + git tag --sign -m "chore(release): Release v${NEW_VERSION}" v${NEW_VERSION} + git push --tags origin "b${MAJOR}.${MINOR}.z" + ``` +- Packaging binary dependency crates + ```bash + cd src/bin/shim-kvm; cargo publish -v --target x86_64-unknown-none; cd .. + cd src/bin/shim-sgx; cargo publish -v --target x86_64-unknown-none; cd .. + cd src/bin/exec-wasmtime; cargo publish -v --target x86_64-unknown-none; cd ../.. + ``` +- Update enarx dependencies + ```bash + export UPDATED_BINDEPS=(enarx-exec-wasmtime enarx-shim-kvm enarx-shim-sgx) + for p in ${UPDATED_PREREQUISTES[@]]}; do + cargo update -p "${p}" + done + ``` +- Commit change and push to repo + ```bash + git commit -asS --amend + git push --force origin "release/${NEW_VERSION}" + ``` +- Create and push `git` tag + ```bash + git tag --sign -m "chore(release): Release v${NEW_VERSION}" v${NEW_VERSION} + git push --tags --force origin "b${MAJOR}.${MINOR}.z" + ``` +- Create a PR + ```bash + gh pr create -t "chore(release): Release v${NEW_VERSION}" \ + -b "chore(release): Release v${NEW_VERSION}" \ + -B "b${MAJOR}.${MINOR}.z" \ + -R enarx/${REPO} + ``` +- Confirm that changes passed on CI and merge PR +- Checkout merged release branch + ```bash + git fetch --all + git branch -u upstream/"b${MAJOR}.${MINOR}.z" + git reset --hard upstream/"b${MAJOR}.${MINOR}.z" + ``` +- Tag the new release on upstream + ```bash + git tag --sign -m "chore(release): Release v${NEW_VERSION}" v${NEW_VERSION} + git push --tags upstream "b${MAJOR}.${MINOR}.z" + ``` +- Cargo publish + > **NOTE: ** Assuming cargo credentials are cached + ```bash + cargo publish -v + ``` +- Create a release PR + ```bash + gh pr create -t "Release v${NEW_VERSION}" \ + -b "" + -B main \ + -R enarx/${REPO} + ``` +- Merge release PR +- Create draft GitHub release + ```bash + gh release create -d --generate-notes "v${NEW_VERSION}" + ``` +- Update release notes on draft release +- Publish release +- Send notification to RocketChat #annoucements & #general channels +- Assign issue to post release to social media channels diff --git a/sidebars.js b/sidebars.js index af7922a25..3c2857a75 100644 --- a/sidebars.js +++ b/sidebars.js @@ -41,7 +41,7 @@ const sidebars = { { type: 'category', label: 'Contributing Guide', - items: ['Contributing/Introduction','Contributing/Onboarding','Contributing/Code','Contributing/Coding-Style','Contributing/Git-hook','Contributing/PRs','Contributing/Issues','Contributing/RFCs','Contributing/Docs','Contributing/Outreach','Contributing/Lab'], + items: ['Contributing/Introduction','Contributing/Onboarding','Contributing/Code','Contributing/Coding-Style','Contributing/Git-hook','Contributing/PRs','Contributing/Issues','Contributing/RFCs','Contributing/Docs','Contributing/Outreach','Contributing/Lab', 'Contributing/Release'], }, { type: 'category',