communique 1.4.1

Editorialized release notes powered by AI
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

# Configuration

communiqué is configured via a `communique.toml` manifest in your repository root. Generate one with:

```sh
communique init
```

## Directives

### `system_extra`

Additional instructions injected into the system prompt. Use this to shape the tone, style, or conventions of your output.

```toml
system_extra = """
Write in a casual, friendly tone.
Always mention breaking changes prominently.
"""
```

### `context`

Supplemental context included in every generation request. Useful for project descriptions or domain knowledge the agent should always have access to.

```toml
context = """
This is a Rust CLI tool for managing cloud infrastructure.
Our users are DevOps engineers and SREs.
"""
```

### `[defaults]`

Default parameters for generation. All values can be overridden via CLI flags.

```toml
[defaults]
model = "claude-fable-5-1"
max_tokens = 16384
repo = "owner/repo"
```

| Key | Description | Default |
|-----|-------------|---------|
| `model` | Model identifier | `claude-fable-5-1` |
| `max_tokens` | Maximum tokens permitted per model response (billing is based on actual usage) | `16384` |
| `repo` | GitHub repo in `owner/repo` format | Auto-detected from git remote |

## Resolution Order

Configuration is resolved with the following precedence:

1. CLI flags (highest priority)
2. `communique.toml` defaults
3. Built-in defaults

## Package releases

Define separate scopes and changelog destinations in a monorepo:

```toml
[packages.cli]
paths = ["crates/cli", "crates/shared"]
tag_pattern = "cli/v*"
channel = "stable"
changelog_path = "crates/cli/CHANGELOG.md"
```

Run `communique generate cli/v2.0.0 --package cli --changelog`.
CLI `--path` values replace the configured paths; other explicit flags override
individual package defaults. Paths are literal repository-relative files or
directories, not glob patterns. The model can inspect other files for context,
but is instructed to describe only changes in the filtered commit list.

`--tag-pattern 'cli/v*'` filters candidate baseline tags using Git's glob syntax.
Candidates must be reachable from the target commit. `--channel stable` excludes
prerelease tags (such as `v2.0.0-beta.1`); `--channel all` includes them
and is the default. An explicit previous reference takes precedence over automatic
selection. The selected range is printed before generation.

## Editorial label rules

```toml
[rules]
include_labels = ["release-note:include"]
exclude_labels = ["release-note:skip", "internal"]

[rules.categories]
"bug" = "Fixed"
"enhancement" = "Added"
```

Rules use labels from PR references in commit subjects (`(#123)`). They require
`GITHUB_TOKEN`; inaccessible PRs cause generation to fail rather than silently
ignore the rules. Include labels override exclude labels and the default filter
for internal changes. Excluded commits are removed from the initial change list;
inclusion and category rules are supplied as explicit model instructions.
Commits without recognized PR references use the normal editorial policy.

## Review, edit, and publish

```sh
communique generate v2.0.0 --draft release.json --review-report review.md \
  --migration-guide upgrade.md
# Edit release_title, release_body, or changelog in release.json.
communique publish release.json --dry-run
communique publish release.json
```

The JSON draft records the repository, tag, target commit, previous reference,
title, body, changelog, and review. Publishing uses the edited title and body
without another model request. Before updating, it resolves the remote tag and
requires it to match the commit recorded when generation began. A moved or missing
tag stops publication; regenerate and review the draft before trying again.
The plain `--dry-run` preview is offline and does not check the remote tag.
Publishing updates an existing GitHub Release and requires
`GITHUB_TOKEN`; it does not write the saved changelog to disk. Draft generation
cannot be combined with `--github-release`.

Coverage reports list each scoped commit as included, omitted, or uncertain with
a source link and reason. Model assessments are advisory; missing, duplicate, or
invalid assessments become uncertain, and explicit label exclusions are recorded
separately. A requested migration guide contains affected users, upgrade steps,
and verified examples, or an explicit statement that no migration is needed.
If the model fails to return a requested guide, generation fails before publishing.

### Preserve hand-written release text

Use `--preserve-sections` with `--github-release` or `--draft` to manage only this
part of a release:

```markdown
Installation instructions and announcements stay here.

<!-- communique:start -->
Generated release notes go here.
<!-- communique:end -->

Maintainer notes stay here too.
```

The model receives only managed content as existing-release and style context,
and is instructed to omit markers and surrounding hand-written text.
If markers are absent, a marked section is appended to the existing body. Invalid
or repeated markers cause an error. The existing release title is preserved in
this mode. `publish --dry-run` fetches the existing release when merging a marked
section, so that preview requires GitHub authentication too.