How Sacho fits together

Sacho keeps unreleased changelog entries beside the changes they describe. Each entry starts as a small Markdown file called a fragment. The fragments are the source of truth until release day.

source change
    +
fragment in changes.d/
    │
    ├── sacho fmt / sacho check
    │
    ├── generated unreleased region in CHANGES.md
    │
    └── sacho release
            │
            ├── dated, frozen section in CHANGES.md
            └── consumed fragments removed

This split gives the two forms different jobs. Fragments travel with commits through version-control operations. The changelog is the document users read.

Repository state

A typical repository contains these files:

sacho.toml
changes.d/
  next
  clear-function.md
CHANGES.md

sacho.toml describes the repository. It names the changelog and fragment paths, chooses a version-control preset, and can define sections or missing fragment checks.

changes.d/next holds the version being prepared. The other Markdown files in changes.d/ are fragments.

CHANGES.md contains released history. By default, it also contains a generated preview of the next release. That preview is called the unreleased region.

Two kinds of prose

A commit message records work for other contributors. A changelog entry records the difference a user will encounter when upgrading. A refactoring may deserve a careful commit message and no changelog entry. A one-line security fix may need a prominent changelog entry.

Sacho checks and assembles prose, but it does not write it. Read Philosophy for the reasoning behind that boundary.

What to read next

Read Fragments for the input format and naming conventions. The changelog lifecycle explains materialization, release, and carrying entries between branches. Repositories with several packages or components should also read Sections.