Burnout
# Releasing A release is a decision that a person makes. The workflow does the rest, and it does nothing until a tag tells it to. ## Before a release Every item has to be true, and not only probably true. - CI is green on the commit that the tag will name. That includes the job that packages the five crates for crates.io. - The exit test of the phase that the release belongs to has passed, on the hardware it names. [The roadmap](roadmap.md) says which test that is. - The version in the root `Cargo.toml` is the version of the release. ## Cut a release 1. Set `version` under `[workspace.package]` in the root `Cargo.toml`, and the same version for the four crates under `[workspace.dependencies]`. Commit it. The commit subject names no version number. 2. Push, and wait for CI to pass on that commit. 3. Tag the commit and push the tag: git tag v0.1.0 git push origin v0.1.0 4. The [release workflow](../.github/workflows/release.yml) builds twelve binaries, six of `burnout` and six of the program with windows, `burnout-gui`. It hashes them, attests each one, and opens a **draft** release. It refuses a tag that disagrees with the version in `Cargo.toml`, because that binary would name a release it does not belong to. 5. Open the draft. Read the list of assets: twelve binaries and `SHA256SUMS`. Publish it. 6. Publish the five crates to crates.io, from a clean checkout of the tag, on a machine where `cargo login` holds the token: git checkout v0.1.0 cargo publish --workspace --locked Cargo publishes them in the order of their dependencies: `burnout-core`, `burnout-iso`, `burnout-layout`, `burnout-wim`, and then `burnout`. A version on crates.io can be yanked, and never deleted. `burnout-gui` does not go to crates.io. 7. Write the Homebrew formula from the `SHA256SUMS` of the release, and commit it to the tap, [Stiven-Gjekaj/homebrew-tap](https://github.com/Stiven-Gjekaj/homebrew-tap). A person writes that commit. No bot pushes to the tap. gh release download v0.1.0 --pattern SHA256SUMS --dir release scripts/homebrew-formula.sh 0.1.0 release/SHA256SUMS > ../homebrew-tap/Formula/burnout.rb scripts/homebrew-gui-formula.sh 0.1.0 release/SHA256SUMS > ../homebrew-tap/Formula/burnout-gui.rb Commit the two formulas together. The program refuses a `burnout` of another version, so the tap never holds one without the other. Then check them the way a user installs them: brew install stiven-gjekaj/tap/burnout-gui burnout --version burnout-gui --version Since version 1.0.0, two more channels take each release, and [the roadmap](roadmap.md) says why they waited until then. 8. Write the Scoop manifest into the bucket, [Stiven-Gjekaj/scoop-bucket](https://github.com/Stiven-Gjekaj/scoop-bucket), and commit it there. A person writes that commit. No bot pushes to the bucket. scripts/scoop-manifest.sh 1.0.0 release/SHA256SUMS > ../scoop-bucket/bucket/burnout.json scripts/scoop-gui-manifest.sh 1.0.0 release/SHA256SUMS > ../scoop-bucket/bucket/burnout-gui.json 9. Write the winget manifest into a branch of the fork [Stiven-Gjekaj/winget-pkgs](https://github.com/Stiven-Gjekaj/winget-pkgs), check it on Windows, and open a pull request to [microsoft/winget-pkgs](https://github.com/microsoft/winget-pkgs) with it. The repository holds hundreds of thousands of files, so sync the fork and clone only the folder of Burnout: gh repo sync Stiven-Gjekaj/winget-pkgs git clone --depth 1 --filter=blob:none --sparse https://github.com/Stiven-Gjekaj/winget-pkgs.git ../winget-pkgs git -C ../winget-pkgs sparse-checkout set manifests/s/Stiven-Gjekaj git -C ../winget-pkgs checkout -b Stiven-Gjekaj.Burnout-1.0.0 scripts/winget-manifest.sh 1.0.0 release/SHA256SUMS ../winget-pkgs winget validate --manifest ..\winget-pkgs\manifests\s\Stiven-Gjekaj\Burnout\1.0.0 The title of the pull request is `New package: Stiven-Gjekaj.Burnout version 1.0.0` for the first version, and `Update: Stiven-Gjekaj.Burnout to ` for each later one. Follow the template of the pull request, and say which checks ran. Microsoft checks the pull request, and a bot merges it. The first pull request of an account asks its owner to sign the Contributor License Agreement of Microsoft. 10. Open a second pull request for the program with windows. winget-pkgs takes one package in each pull request. Its package depends on the package of `burnout` of the same version, so open it after the first. git -C ../winget-pkgs checkout -b Stiven-Gjekaj.BurnoutGUI-1.0.0 master scripts/winget-gui-manifest.sh 1.0.0 release/SHA256SUMS ../winget-pkgs winget validate --manifest ..\winget-pkgs\manifests\s\Stiven-Gjekaj\BurnoutGUI\1.0.0 The title is `New package: Stiven-Gjekaj.BurnoutGUI version ` for the first version, and `Update: Stiven-Gjekaj.BurnoutGUI to ` for each later one. The draft is the last point where nobody outside the project has the files. This tool erases drives, so a person looks before anybody can download it. The crates and the tap come after it for the same reason. | Asset | Host | | --- | --- | | `burnout--x86_64-unknown-linux-musl` | Linux on x86_64, any distribution | | `burnout--aarch64-unknown-linux-musl` | Linux on arm64, any distribution | | `burnout--x86_64-apple-darwin` | macOS on Intel | | `burnout--aarch64-apple-darwin` | macOS on Apple silicon | | `burnout--x86_64-pc-windows-msvc.exe` | Windows on x86_64 | | `burnout--aarch64-pc-windows-msvc.exe` | Windows on arm64 | | `burnout-gui--x86_64-unknown-linux-gnu` | Linux on x86_64 with glibc 2.35 or later | | `burnout-gui--aarch64-unknown-linux-gnu` | Linux on arm64 with glibc 2.35 or later | | `burnout-gui--x86_64-apple-darwin` | macOS on Intel | | `burnout-gui--aarch64-apple-darwin` | macOS on Apple silicon | | `burnout-gui--x86_64-pc-windows-msvc.exe` | Windows on x86_64 | | `burnout-gui--aarch64-pc-windows-msvc.exe` | Windows on arm64 | The Linux binaries of `burnout` carry their own C library, and the Windows binaries carry the Microsoft C runtime, so none of them needs anything installed beside it. The Linux binaries of `burnout-gui` use the glibc and the fontconfig of the desktop, because a program with windows loads the libraries of the desktop. Ubuntu 22.04 builds them, so a distribution with glibc 2.35 or later runs them. ## Test the workflow without a release gh workflow run release.yml A run started by hand builds all twelve and hashes them, and it publishes nothing. It makes no attestation either, because on a public repository an attestation goes into the public Sigstore log. The files wait in the run as an artifact named `dist`: gh run download --name dist ## Check a download Two checks, and they answer different questions. The checksum says that the file arrived whole: shasum -a 256 -c SHA256SUMS --ignore-missing The attestation says that this file came out of this repository, from the commit that the tag names, through the release workflow: gh attestation verify burnout-0.1.0-aarch64-apple-darwin --repo Stiven-Gjekaj/burnout The attestation is the stronger claim, and it is the reason this project has no code signing certificate. [The roadmap](roadmap.md) records that decision. ### The warning that a browser download brings A browser marks a downloaded file, and both desktop systems then warn before they run it. The file is the same file. The warning is about how it arrived. - **macOS** refuses to start a quarantined binary that no paid certificate signed. After both checks above pass, take the mark off: xattr -d com.apple.quarantine burnout-0.1.0-aarch64-apple-darwin - **Windows** SmartScreen shows "Windows protected your PC". Select **More info**, then **Run anyway**. A file fetched with `curl` or `gh release download` carries no mark and brings no warning.