colophon propose¶
Description¶
Write the release branch and open or update its merge request
Re-cut the release branch from its target, write the changelog into it, and open or update the merge request that proposes the release. The branch is cut from the target on every run rather than kept up to date with it, so the merge request can never be behind. Nothing is tagged and nothing is published; that is `publish`. A repository with nothing to release, or one holding releases, reports so and exits zero.
Usage¶
Run colophon propose --help for the authoritative, always-current flag set.
Flags¶
| Flag | Description | Default |
|---|---|---|
--author-email |
Email on the release commit | [email protected] |
--author-name |
Name on the release commit | colophon |
--branch |
Release branch to write | derived: colophon/release/<target> |
--dry-run |
Print the merge request that would be opened, and write nothing | false |
--remote |
Git remote to read and push to | origin |
--forge |
Forge the remote is on when its host does not say: gitlab, github or gitea. Same as forge in .colophon.yaml; both must agree when given. |
empty |
-C, --repo |
Path to the git repository | . |
--target |
Branch to release from | main |
Needs a forge token in <FORGE>_TOKEN. See the
configuration reference.
Components¶
With components in the manifest, one request carries a section per
component that has something to release, root first, then components in
manifest order. The release commit writes the root's CHANGELOG.md and each
carried component's <dir>/CHANGELOG.md, and its subject names every tag the
request proposes: chore(main): release v1.2.0 lint/v0.7.0, or
chore(main): release lint/v0.7.0 when only a component has work. A
component's changelog heading carries its whole tag, ## [lint/v0.7.0](…).
A held component (hold: true under it) is left out of the request and
named in the report with its reason; the root's hold leaves the root out
the same way. When everything releasable is held, nothing is proposed and
each hold is listed. Merging the request releases every tag it names, and
propose refuses to propose the same set of tags again while the target's
tip is that release commit.
Global flags¶
| Flag | Description | Default |
|---|---|---|
--ci |
Indicates the tool is running in a CI environment | false |
--config |
Config files to use (repeatable) | /etc/colophon/config.yaml, ~/.colophon/config.yaml |
--debug |
Force debug log output | false |
--output |
Output format: text or json |
text |
Run colophon <command> --help for the authoritative, always-current flag set.