Skip to content

RELEASE.md

Latest commit

 

History

History
94 lines (77 loc) · 3.67 KB

RELEASE.md

File metadata and controls

94 lines (77 loc) · 3.67 KB
Raw

Bollard Release Process

This document outlines the steps for releasing a new version of Bollard. Follow these instructions carefully to ensure a smooth release process.

1. Update the Moby Compatibility Input

  1. Identify the Moby API release to support and update the inputSpec URL in codegen/swagger/pom.xml.
  2. Confirm that the URL references the intended immutable Moby release.

2. Regenerate and Validate BuildKit Protobuf Files

Steps for bollard-buildkit-proto

Run the preferred workflow from the repository root:

cargo xtask buildkit update
cargo xtask buildkit check

update derives the immutable Moby and BuildKit compatibility baseline from codegen/swagger/pom.xml, fetches the dependency-classified protobuf sources, applies named transformations with exact match counts, and stages source and transformed-output hashes. It replaces checked-in resources only after the complete preparation succeeds, then writes the complete provenance lock atomically. check enforces the lock without network access; use cargo xtask buildkit check --online during release preparation to re-fetch and verify upstream source hashes. The xtask uses the vendored protoc and exact generator versions recorded in the provenance lock; do not set PROTOC or PROTOC_INCLUDE while running it.

  1. Check for transient dependency updates between bollard and bollard-buildkit-proto (e.g., tonic).
  2. Run both provenance checks and review the lock, resource, and generated Rust diffs: 
    cargo xtask buildkit check
cargo xtask buildkit check --online
  3. Review the provenance and generated Rust diffs.
  4. Verify the build and full test suite, including clippy, formatting, semver, and audit checks.

3. Update Swagger-Generated Files

Steps for bollard-swagger

  1. Check for transient dependency updates between bollard and bollard-buildkit-proto (e.g., chrono).
  2. Update the packageVersion field:
    • The first two numbers represent the Moby API version.
    • The third number corresponds to Bollard's internal codegen version.
    • The digits following rc match the Moby release tag.
    • Format: [API-major].[API-minor].[bollard-codegen-version]-rc.[moby-tag-major][moby-tag-minor].[moby-tag-patch].
  3. Modify Cargo.mustache to reference the new bollard-buildkit-proto version.
  4. Generate the new Swagger bindings: 
    mvn -D org.slf4j.simpleLogger.defaultLogLevel=warn clean compiler:compile generate-resources
  5. Validate the build:
    • Run a build in the root directory.
    • Temporarily add a path dependency in Cargo.toml to verify correctness.
  6. Review the generated Swagger diff alongside the protobuf diff. Do not run cargo fmt over generated Swagger stubs; regenerate them through Maven.

4. Publish in Dependency Order

  1. Package and publish bollard-buildkit-proto: 
    (cd codegen/proto && cargo package && cargo publish)
  2. Update the generated stubs and Bollard manifests to reference the released proto version, then package and publish bollard-stubs: 
    (cd codegen/swagger && cargo package && cargo publish)
  3. Update Bollard's dependencies and any generated API or documentation as needed. Regenerate the README: 
    cargo readme --no-title > README.md

5. Publish Bollard

  1. Bump the crate version as necessary.
  2. Package and publish the release: 
    cargo package
cargo publish
  3. Create a GitHub Release tag (this should be autogenerated).

Following these steps ensures consistency and reliability when publishing new versions of Bollard. If any issues arise, review the steps carefully or consult the project maintainers for guidance.