Skip to content

Latest commit

 

History

History
256 lines (199 loc) · 9.04 KB

RELEASING.md

File metadata and controls

256 lines (199 loc) · 9.04 KB

Release Procedure

This document defines the manual, maintainer-controlled release process for Eggsec. Release cadence and publication are explicit maintainer decisions.

Non-negotiable policy

  • No GitHub Actions workflow publishes any package.
  • No tag triggers artifact construction, publication, or GitHub Release creation.
  • No workflow requires registry credentials or trusted-publishing OIDC permissions.
  • The final publish command is typed explicitly by a maintainer in a local or maintainer-controlled environment.
  • Validation and publication are separate steps.
  • Failed publication is handled according to registry immutability rules; an already published version is never overwritten.

Registries

Registry Package Publication method
crates.io eggsec-core, eggsec-policy, eggsec-report-model, eggsec-agent, eggsec-runtime, eggsec-runtime-independent leaves (eggsec-transport, eggsec-transport-eggfetch, eggsec-tool-core, eggsec-db-lab, eggsec-mobile-lab, eggsec-udp-scan, eggsec-output, eggsec-ui-model, eggsec-web-proxy, eggsec-daemon-protocol), eggsec, eggsec-daemon cargo publish (manual)
PyPI eggsec maturin publish (manual)
TestPyPI eggsec Optional, manual rehearsal

Note: eggsec-cli, eggsec-tui, eggsec-python, and the three knowledge-corpus leaves (eggsec-service-db, eggsec-secrets, eggsec-payloads) have publish = false and are not published to crates.io.

The NSE runtime is consumed as the published eggsec-nse = "0.2.0" crates.io dependency behind the optional engine nse feature (engine manifest + Cargo.lock must agree — guard Check 144). It is not a member of this workspace release sequence and is not published from this repo.

Supported release host

The validated release host is Linux (the CI and primary development environment). make release-check has been verified end-to-end on Linux.

macOS and Windows CI jobs verify that the workspace compiles on those platforms, but release-check.sh has not been executed end-to-end on macOS. Linux is the tested and supported release host; macOS release-script compatibility is unverified.

Pre-release validation

Run the local release check script:

make release-check
# or directly:
scripts/release-check.sh <version>

This validates without publishing. The Rust portion has three deliberately separate levels:

  • Level A — local archives (default): the helper derives the publishable set from Cargo metadata and runs cargo package --workspace --no-verify --target-dir <isolated-target>, excluding eggsec-cli, eggsec-tui, and eggsec-python. Cargo creates the .crate files; the helper emits an exact JSONL inventory, records each archive's size and SHA-256, inspects the normalized manifest/content, and runs standalone cargo metadata --no-deps --offline outside the source workspace. Any Cargo or inspection failure is a failure.
  • Level B — registry preflight (optional locally): EGGSEC_RELEASE_REGISTRY_PREFLIGHT=1 make release-check runs cargo publish --dry-run in dependency order. This is registry-sensitive and is required layer by layer immediately before a staged publication.
  • Level C — publication (manual): actual cargo publish commands are typed explicitly by a maintainer. release-check.sh, tests, and CI never publish packages.

The default check validates without publishing:

  1. Clean working tree and explicit current commit
  2. Version alignment across Cargo.toml, pyproject.toml, and optional argument
  3. Package graph validation via scripts/release-package-graph.py
  4. make check (mandatory Rust CI contract)
  5. make check-python (mandatory Python CI contract, skippable with EGGSEC_RELEASE_SKIP_PYTHON=1)
  6. Cargo-native workspace package generation, exact archive inventory, standalone manifest parsing, and archive inspection
  7. Python wheel and sdist build
  8. Fresh-environment wheel installation and smoke test
  9. Artifact inventory (filenames, sizes, SHA-256 hashes)

Optional environment controls:

EGGSEC_RELEASE_SKIP_PYTHON=1         # skip Python checks (Rust-only release)
EGGSEC_RELEASE_REGISTRY_PREFLIGHT=1  # run cargo publish --dry-run (network-sensitive)
EGGSEC_RELEASE_KEEP_ARTIFACTS=1      # do not clean build artifacts on exit

Optional full validation (pre-release, not required for every merge):

make check-full

Rust crates / crates.io

Prerequisites

  • Authenticated with crates.io using the maintainer's chosen mechanism (e.g., cargo login with an API token).
  • All version files aligned and clean working tree.

Dependency order

Publish crates in dependency order. The authoritative order is generated by:

python scripts/release-package-graph.py order

Current publishable set and order (dependencies before dependents; regenerate with the command above after any manifest change):

  1. eggsec-core
  2. eggsec-agent
  3. eggsec-policy
  4. eggsec-report-model
  5. eggsec-db-lab
  6. eggsec-mobile-lab
  7. eggsec-output
  8. eggsec-runtime
  9. eggsec-daemon-protocol
  10. eggsec-tool-core
  11. eggsec-transport
  12. eggsec-transport-eggfetch
  13. eggsec-udp-scan
  14. eggsec-ui-model
  15. eggsec-web-proxy
  16. eggsec
  17. eggsec-daemon

Wait for each crate to appear on crates.io before publishing dependents. The staged sequence is:

validate all local archives
publish one dependency layer
wait for registry visibility
run cargo publish --dry-run for the next layer
publish the next layer
repeat

A registry failure, timeout, or unavailable dependency remains a failure or unavailable result; it is never converted into a local archive pass.

Private crates (not published to crates.io): eggsec-cli, eggsec-tui, eggsec-python, eggsec-service-db, eggsec-secrets, eggsec-payloads. The standalone eggsec-nse runtime is released from its own repository; Eggsec consumes it as the published crates.io release eggsec-nse 0.2.0, so it is not part of this workspace release sequence.

Commands

cargo publish -p eggsec-core
# wait for availability...
cargo publish -p eggsec-agent
cargo publish -p eggsec-policy
cargo publish -p eggsec-report-model
cargo publish -p eggsec-db-lab
cargo publish -p eggsec-mobile-lab
cargo publish -p eggsec-output
cargo publish -p eggsec-runtime
cargo publish -p eggsec-daemon-protocol
cargo publish -p eggsec-tool-core
cargo publish -p eggsec-transport
cargo publish -p eggsec-transport-eggfetch
cargo publish -p eggsec-udp-scan
cargo publish -p eggsec-ui-model
cargo publish -p eggsec-web-proxy
# wait for availability...
cargo publish -p eggsec
# wait for availability...
cargo publish -p eggsec-daemon

Post-publication

  • Never attempt to overwrite an immutable version. Bump the version for corrections.
  • Tag only after the maintainer decides the publication state warrants it.

Python package / PyPI

Prerequisites

  • Authenticated with PyPI (API token in ~/.pypirc or environment).
  • maturin and twine installed.
  • Release check passed.

Build

cd crates/eggsec-python
rm -rf dist/ target/wheels/
maturin build --release --out dist
maturin sdist --out dist
python -m twine check dist/*

Publish

Preferred command:

cd crates/eggsec-python
maturin publish

Or manually:

python -m twine upload dist/*

Optional TestPyPI rehearsal

TestPyPI is opt-in, not a release gate. If used, the rehearsal version must be unique because package indexes are immutable.

python -m twine upload --repository testpypi dist/*

GitHub tags/releases

Tagging and GitHub Release notes are optional manual follow-up activities. They must not publish registry packages or trigger release workflows.

If maintainers create a GitHub Release manually, document it as metadata/distribution convenience after registry publication, not the source of release cadence.

Version bump workflow

  1. Update version in workspace Cargo.toml.
  2. Update version in crates/eggsec-python/pyproject.toml to match.
  3. Update every version-qualified internal path dependency in publishable manifests (the version = "..." alongside path = "..."), including target-specific and aliased dependencies. Inventory them with: python3 scripts/release-package-graph.py version-locations.
  4. Regenerate Cargo.lock only when required by the manifest change; review third-party changes and use --locked checks.
  5. Run python3 scripts/release-package-graph.py validate and make release-check to identify stale versions and validate archives.
  6. Publish crates and/or Python package as described above.
  7. Tag the release (optional, after publication): git tag v<version>.
  8. Push tag: git push origin v<version>.

Recovery from failed publication

  • If a version is partially published (some crates succeeded, others failed), complete the remaining publishes if possible. If the failing crate cannot be fixed without a code change, bump the version and start fresh.
  • Never overwrite an immutable published version.