elastic / elastic/package-spec
[Change Proposal] Enforcing structure inside `changelog.yml` files
- Dominant language
- Go
- Stars
- 20
- Forks
- 93
- Avg merge
- 15h 10m
- Merged PRs (30d)
- 12
Description
## Problem statement
With https://github.com/elastic/package-spec/pull/131, packages are now expected to have a `changelog.yml` file in their root folders. That PR introduced the structure (syntax) for package changelogs but there are two unanswered questions about the semantics of the changelog entries:
1. in the package's `changelog.yml` file, where should unreleased changes be stored?
2. what should be the relationship of the `version` specified in a package's `manifest.yml` file to any of the versions specified in the package's `changelog.yml` file?
## Proposal
The structure of package's `changelog.yml` files is expected to be like so:
```yaml
- version: x.y.z
changes:
- description: ...
type: ...
link: ...
- description: ...
type: ...
link: ...
- version: p.q.r
changes:
- description: ...
type: ...
link: ...
- description: ...
type: ...
link: ...
- version: a.b.c
changes:
- description: ...
type: ...
link: ...
- description: ...
type: ...
link: ...
```
* We introduce a special version, `next`, that is expected to be **first** entry in the top-level array in `changelog.yml` files (where `x.y.z` is in the snippet above). All the `changes` under this version will be unreleased ones.
* We expect that the **second** entry in the top-level array in `changelog.yml` files (where `p.q.r` is in the snippet above) matches exactly the value of `version` in the package's `manifest.yml` file.
This allows a package developer to accumulate unreleased changes in the changelog under the first entry (`next`). When the package developer is ready to release a new version of the package, they do the following, all as part of a single PR:
1. bump up the value of `version` in their package's `manifest.yml`,
2. replace `next` with the new value of `version` in their package's `manifest.yml`, and
3. add a new `next` entry at the top of their package's `changelog.yml` file with an empty list of `changes` under it.
Contributor guide
Assessment
This issue has not been assessed yet.