Skip to main content

Deployed Changelog

x4 changelog generates changelog artifacts from deployed evidence. It is designed for environment-specific release notes: a commit appears in a dev or prod changelog only after evidence says that commit was deployed to that environment.

The implementation is deterministic and file-backed in the current slice. It does not call GitHub, Azure, APIM, product storage, or product repos with write credentials unless a future publication adapter is explicitly wired in.

Commands​

x4 changelog registry validate
x4 changelog validate-artifact
x4 changelog bootstrap-plan
x4 changelog generate
x4 changelog backfill
x4 changelog polish
x4 changelog llm-review
x4 changelog workflow describe
x4 changelog workflow run

Registry​

Changelog registrations live under the X4 registry changelog.repos key, or in a standalone changelog registry file:

changelog:
  repos:
    - repo: X4Org/Mastra-Agent-Framework
      defaultBranch: main
      configPath: .x4/changelog.config.yml
      environments:
        dev:
          evidenceProvider: manual-json
          ingestUrl: https://dev-apim.example.com/internal/x4/changelog/ingest

Validate the registration:

x4 changelog registry validate --registry registry/x4-pilot-registry.yaml

Generate From Evidence​

x4 changelog generate \
  --repo X4Org/Mastra-Agent-Framework \
  --environment dev \
  --previous-evidence previous.json \
  --new-evidence new.json \
  --out temp/changelog-generate

The output includes a schemaVersion 1 Keep a Changelog-style artifact and gate metadata. X4 validates scope isolation, category structure, source commits, and review-needed signals before the artifact is considered publishable.

Backfill​

Backfill starts from a reviewed scope boundary and walks git history to create a draft historical changelog:

x4 changelog backfill \
  --repo X4Org/Mastra-Agent-Framework \
  --environment dev \
  --repo-path /path/to/Mastra-Agent-Framework \
  --from-ref <scope-start-ref> \
  --to-ref HEAD \
  --out temp/changelog-backfill

Backfill does not blindly turn every commit into a customer-facing bullet. It filters generated, CI-only, merge-only, and internal-only changes unless repo configuration maps them to a valid scope and category.

LLM Review Boundary​

The LLM layer is a verifier, not the author. X4 first builds the changelog from structured evidence, then can ask a model to review scoped entries for leakage, cross-product wording, unsupported claims, or internal implementation detail:

x4 changelog llm-review \
  --artifact temp/changelog-generate/deployed-changelog.json \
  --out temp/changelog-llm-review

Model findings are grounded against existing artifact entries. Hallucinated findings or ungrounded rewrites are rejected.

Workflow Contract​

The stable workflow ids are:

x4.deployed-changelog.generate
x4.deployed-changelog.bootstrap-repo
x4.deployed-changelog.backfill

Describe the workflow contract:

x4 changelog workflow describe

Run the deterministic generate contract:

x4 changelog workflow run \
  --mode generate \
  --repo X4Org/Mastra-Agent-Framework \
  --environment dev \
  --previous-evidence previous.json \
  --new-evidence new.json \
  --out temp/changelog-workflow

See the deeper implementation notes in docs/deployed-changelog.md when working inside the source repository.