elastic / elastic/package-spec

[Change Proposal] Enforcing structure inside `changelog.yml` files

Open
#140 22 comments 0 reactions 0 assignees View on GitHub
discuss
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.