The Versioning Strategy for macro-inc/macro Releases: Semantic Versioning in a Mono-Repo

Macro implements a single-source semantic versioning model where all workspace crates share a unified version string defined in the root Cargo.toml, with releases triggered exclusively by Git tags and automated through the release-production GitHub Actions workflow.

The macro-inc/macro repository manages a Rust workspace containing multiple crates that require synchronized release cycles. Understanding the versioning strategy for macro-inc/macro releases is essential for contributors preparing to ship new features or patches. The project follows strict semantic versioning principles combined with a mono-repo approach that ensures consistency across all distributed packages.

Semantic Versioning in the Workspace Root

Single-Source Version Control

All crates within the Macro workspace inherit their version from the top-level Cargo.toml. In [Cargo.toml](https://github.com/macro-inc/macro/blob/main/Cargo.toml), the version = "0.1.0" field serves as the canonical source of truth, with individual crate manifests referencing this value via workspace inheritance. This ensures that every package in the mono-repo maintains identical version numbers during release cycles.

The project adheres to classic semantic versioning conventions: increment MAJOR for breaking changes, MINOR for new public features, and PATCH for bug-only updates.

Release Automation Pipeline

Git Tag-Based Triggers

Releases are initiated through annotated Git tags rather than manual workflow dispatches. When a maintainer pushes a tag matching the pattern v*.*.*, the [.github/workflows/release-production.yml](https://github.com/macro-inc/macro/blob/main/.github/workflows/release-production.yml) workflow executes automatically. This approach guarantees that the version string in Cargo.toml corresponds exactly to the Git tag driving the CI pipeline.

The release-production Workflow

The workflow defined in .github/workflows/release-production.yml orchestrates the entire distribution process. Upon detecting a version tag, it compiles Rust binaries in --release mode, constructs Docker images, publishes crates to the registry, and invokes the changelog generator. This consolidates build artifacts, container images, and documentation updates into a single atomic operation.

Automated Changelog Generation

The repository automates release notes through [apps/docs/scripts/generate-changelog.ts](https://github.com/macro-inc/macro/blob/main/apps/docs/scripts/generate-changelog.ts). This TypeScript script executes during the release workflow, parsing commit history to produce MDX-formatted changelog entries that remain synchronized with the tagged version. Each release automatically generates corresponding documentation without manual copy-editing.

Practical Release Workflow

Maintainers follow a standardized four-step process to execute a release:

1. Update the version field in the workspace Cargo.toml to the new semantic version (e.g., "0.2.0").
2. Commit this change to the main branch with a conventional commit message.
3. Create and push an annotated Git tag matching the version.
4. Allow GitHub Actions to handle building, packaging, and publishing via the release-production workflow.

The justfile provides convenience aliases such as just release that encapsulate build commands, streamlining local preparation before CI takeover.

# 1. Bump the version in Cargo.toml (e.g., version = "0.2.0")

# 2. Commit the change

git commit -am "chore: bump to v0.2.0"

# 3. Create and push the annotated tag

git tag -a v0.2.0 -m "Release v0.2.0"
git push origin v0.2.0

# 4. GitHub Actions automatically builds and publishes via release-production.yml

Summary

• Single-source versioning: All crates share one version string defined in the root Cargo.toml.
• Tag-driven releases: The release-production.yml workflow triggers exclusively on Git tags (e.g., v0.1.0).
• Semantic versioning: The project adheres to MAJOR.MINOR.PATCH conventions for breaking changes, features, and fixes.
• Automated documentation: generate-changelog.ts creates MDX changelog entries automatically during each release.
• Unified build process: The justfile provides just release aliases to standardize local release preparation.

Frequently Asked Questions

How does Macro ensure all crates use the same version number?

The workspace root Cargo.toml defines the canonical version field, which all member crates inherit through Cargo's workspace inheritance mechanism. This single-source approach prevents version drift across the mono-repo.

What file triggers the production release pipeline?

The .github/workflows/release-production.yml workflow monitors for pushed Git tags matching semantic version patterns (e.g., v0.2.0). Pushing such a tag automatically initiates the build and publication process.

How is the changelog maintained for each release?

The apps/docs/scripts/generate-changelog.ts script runs during the release workflow, automatically generating MDX-formatted changelog entries from commit history and ensuring documentation stays synchronized with the tagged release.

Can developers use cargo release to automate version bumps?

While the repository supports manual version updates via editing Cargo.toml directly, developers may use tools like cargo release locally, provided they subsequently commit the change and push the corresponding Git tag to trigger the release-production workflow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}