Cider (CI for Dart: Efficient Release)
Cider is a CLI tool for Dart package maintenance. It updates CHANGELOG.md and pubspec.yaml to help automate releases.
Assumptions
Cider expects:
- a
CHANGELOG.md file in the project root
- changelog format compatible with Keep a Changelog
- simple Markdown in changelog entries (no HTML or complex formatting)
- project versions that follow Semantic Versioning 2.0.0
Installation
dart pub global activate cider
Configuration
Configure Cider in pubspec.yaml under cider:
cider:
link_template:
tag: https://github.com/example/project/releases/tag/%tag%
diff: https://github.com/example/project/compare/%from%...%to%
version: v%version%
Placeholders:
%from% - previous version tag%to% - current version tag%tag% - release tag
Project root detection
You can run Cider from any subdirectory. It searches upward for pubspec.yaml.
To override auto-detection:
cider --project-root=/path/to/project version
Changelog commands
These commands modify CHANGELOG.md unless stated otherwise.
Add an entry
cider log <type> <description>
<type>: added, changed, deprecated, removed, fixed, security<description>: one Markdown line
Examples:
cider log changed 'Improve parser performance'
cider log added 'Support workspace mode'
cider log fixed 'Null pointer in changelog parser'
Release Unreleased entries
cider release [options]
Options:
--date - release date (default: today)
If link_template.diff is configured, Cider generates changelog diff links automatically.
Print changes for a version (read-only)
cider describe [<version>] [options]
<version> defaults to Unreleased if omitted
Options:
--only-body - omit section header and link footer
List versions
cider list [options]
Options:
--include-yanked, -y--include-unreleased, -u
Version commands
These commands operate on version in pubspec.yaml.
Print current version (read-only)
cider version
Set version
cider version <new_version>
<new_version> must be SemVer-compatible.
Examples:
| Before |
Command |
After |
| 1.2.3+1 |
cider version 3.2.1 |
3.2.1 |
| 0.2.1-dev |
cider version 0.0.1-alpha+42 |
0.0.1-alpha+42 |
Yank / unyank a release in changelog
cider yank <version>
cider unyank <version>
Yanked versions are marked as [YANKED] in CHANGELOG.md.
Bump version
cider bump <part> [options]
<part> can be:
breaking (y for 0.y.z, otherwise x for x.y.z)majorminorpatchbuildpre (pre-release)release (remove pre-release suffix)
Options:
--keep-build - keep existing build metadata--bump-build - increment build metadata--build=<value> - set build metadata explicitly--pre=<prefix> - set pre-release prefix
Notes:
- For
pre and build, Cider increments the rightmost dot-separated numeric identifier.
- If no numeric identifier exists, Cider appends
.1.
- Per SemVer, build metadata does not affect version precedence.
Examples:
| Before |
Command |
After |
| 1.2.1-alpha+42 |
cider bump breaking |
2.0.0 |
| 0.2.1-alpha+42 |
cider bump breaking |
0.3.0 |
| 0.2.1-alpha+42 |
cider bump major |
1.0.0 |
| 0.2.1-alpha+42 |
cider bump minor |
0.3.0 |
| 0.2.1-alpha+42 |
cider bump patch |
0.2.1 |
| 0.2.1 |
cider bump patch |
0.2.2 |
| 0.2.1-alpha+42 |
cider bump pre |
0.2.1-alpha.1 |
| 1.2.1-alpha+42 |
cider bump breaking --keep-build |
2.0.0+42 |
| 0.2.1-alpha+42 |
cider bump breaking --bump-build |
0.3.0+43 |
| 0.2.1-alpha+42 |
cider bump major --build=2020-02-02 |
1.0.0+2020-02-02 |
| 0.2.1-alpha+42 |
cider bump minor --pre=alpha --bump-build |
0.3.0-alpha+43 |
| 0.2.1-alpha+42 |
cider bump release |
0.2.1 |
| 0.2.1-alpha+42 |
cider bump release --keep-build |
0.2.1+42 |
Exit codes
| Code |
Meaning |
| 0 |
Success |
| 64 |
Usage error (invalid arguments) |
| 65 |
Data error (missing/invalid project files) |
| 70 |
Internal software error (consider opening an issue) |
