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

> Discover macro-inc/macro's semantic versioning strategy. Learn how unified versions, Git tags, and GitHub Actions streamline releases in this mono-repo.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: best-practices
- Published: 2026-08-15

---

**Macro implements a single-source semantic versioning model where all workspace crates share a unified version string defined in the root [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/Cargo.toml). In [[`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/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)](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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/.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)](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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/justfile) provides convenience aliases such as `just release` that encapsulate build commands, streamlining local preparation before CI takeover.

```bash

# 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`](https://github.com/macro-inc/macro/blob/main/Cargo.toml).
- **Tag-driven releases**: The [`release-production.yml`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/.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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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.