Macro Release History Explained: How Versioning, CI, and Changelogs Work

Macro uses a calendar-based versioning scheme (vYYYY.M.D.patch) where GitHub tags trigger automated releases via .github/workflows/release-production.yml, with release history surfaced through the GitHub API, a generated docs changelog, and a repository VERSION file.

The release history of Macro is maintained through a fully automated pipeline that connects Git tags, CI workflows, and documentation generation. This article examines the versioning system, release automation, and how to access historical release data programmatically or through the Macro documentation site.

How Macro Versioning Works

Macro follows a semantic-style versioning scheme based on the calendar format vYYYY.M.D.patch. Each release receives a unique tag such as v2026.4.28.0, which simultaneously identifies the release date and build iteration.

The VERSION file at the repository root stores the current version string as the single source of truth for the build system. When developers bump this file and push a corresponding Git tag, the release pipeline activates automatically.

The version format components:

• YYYY – Full year of release
• M – Month (single digit when < 10, e.g., 4 for April)
• D – Day (may omit leading zero)
• patch – Build iteration for same-day releases (starts at 0)

The Automated Release Pipeline

When a new tag matching the version pattern is pushed, the .github/workflows/release-production.yml workflow triggers and executes the complete release process.

The workflow performs three main operations:

1. Builds all services using just build
2. Packages binaries and uploads them as release assets
3. Creates the GitHub release via gh release create

Here is the relevant artifact upload step from the workflow:

# .github/workflows/release-production.yml

name: Deploy Production Release
...
steps:
  - name: Upload Release Artifacts
    uses: actions/upload-artifact@v3
    with:
      name: macro-release
      path: target/release/*

This ensures every binary is attached to the GitHub release for downstream consumption.

How the Changelog Generator Works

After releases are published, the apps/docs/scripts/generate-changelog.ts script maintains the documentation site's release history. This TypeScript utility:

• Queries the GitHub API for all repository releases
• Groups releases by month for easier navigation
• Generates MDX files consumed by the docs site

The generated changelog lives at apps/docs/changelog/introduction.mdx and provides a browsable alternative to the raw GitHub releases page.

To fetch release data manually, use this API call:

curl -s https://api.github.com/repos/macro-inc/macro/releases |
jq '.[] | {tag_name, name, published_at}'

This returns structured JSON that mirrors what the changelog generator consumes.

Accessing Release History: Three Methods

The Macro release history is available through three synchronized sources:

Method	Location	Best For
GitHub Releases	github.com/macro-inc/macro/releases	Complete archive, download assets
Docs Changelog	docs.macro.com/changelog	Month-grouped browsing, user-friendly format
VERSION file	Repository root VERSION	Build-time version detection

Reading the Current Version Programmatically

The Macro CLI reads the VERSION file at runtime. Here is a Rust implementation that retrieves the current version:

use std::fs;
use std::path::Path;

/// Returns the current Macro version as a string (e.g., "v2026.4.28.0")
fn current_version() -> Result<String, std::io::Error> {
    let version_path = Path::new("VERSION");
    let contents = fs::read_to_string(version_path)?;
    Ok(contents.trim().to_string())
}

This pattern ensures consistency between the tagged release and what the running binary reports.

Recent Release Timeline

Tag	Date (UTC)	Highlights
v2026.4.28.0	2026-04-28	Current stable release (see VERSION)
v2026.3.15.0	2026-03-15	Added AI-enabled agents and improved CRDT sync
v2026.2.07.0	2026-02-07	Introduced multi-account email inboxes
v2026.1.20.0	2026-01-20	First production deployment of the web client

The full release history extends further back on the GitHub Releases page.

Summary

• Macro uses calendar-based versioning (vYYYY.M.D.patch) with the VERSION file as the build source of truth
• Pushing a version tag triggers .github/workflows/release-production.yml to build, package, and publish releases
• apps/docs/scripts/generate-changelog.ts generates the month-grouped changelog from GitHub API data
• Release history is accessible via GitHub Releases, docs.macro.com/changelog, or direct API queries

Frequently Asked Questions

What versioning scheme does Macro use?

Macro uses a calendar-based format vYYYY.M.D.patch that encodes the release date directly into the version string. This is implemented in the repository's VERSION file and enforced by the release workflow in .github/workflows/release-production.yml.

How can I download older Macro releases?

All releases are permanently archived on the GitHub Releases page at github.com/macro-inc/macro/releases. Each release includes compiled binaries as attached assets, downloadable directly or via the GitHub API.

Where does the Macro documentation changelog come from?

The changelog at docs.macro.com/changelog is automatically generated by apps/docs/scripts/generate-changelog.ts, which queries the GitHub API and groups releases by month into MDX files for the documentation site.

Can I check the Macro version from the command line?

Yes. The Macro CLI reads the VERSION file at runtime to report its version. You can also check the repository directly or query the GitHub API for the latest release tag.

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