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

> Discover Macro's release history. Learn about its calendar versioning, CI-driven releases triggered by GitHub tags, and how changelogs are generated.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: release-history
- Published: 2026-08-14

---

**Macro uses a calendar-based versioning scheme (vYYYY.M.D.patch) where GitHub tags trigger automated releases via [`.github/workflows/release-production.yml`](https://github.com/macro-inc/macro/blob/main/.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`](https://github.com/macro-inc/macro/blob/main/.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:

```yaml

# .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`](https://github.com/macro-inc/macro/blob/main/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:

```bash
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:

```rust
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`](https://github.com/macro-inc/macro/blob/main/.github/workflows/release-production.yml)** to build, package, and publish releases
- **[`apps/docs/scripts/generate-changelog.ts`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/.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`](https://github.com/macro-inc/macro/blob/main/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.