Introducing package CHANGELOGs

[ycombinator]

What does this PR do?

This PR enhances the package spec to require CHANGELOG.yml files at the root folder of every package.

Why is it important?

So package consumers can track changes to packages across versions.

Checklist

• I have added test packages to code/go/internal/validator/test/packages that prove my change is effective.
• I have added an entry in versions/N/changelog.yml.

Related issues

• Related: Package CHANGELOGs #17

[elasticmachine]

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

• Build Cause: Pull request #131 updated

• Start Time: 2021-02-10T14:29:15.964+0000

• Duration: 2 min 2 sec

• Commit: ebe7262

Trends 🧪

[mtojek]

Nice! Looking forward to seeing this in action.

[ycombinator]

@mtojek Thanks for reviewing this PR but I thought of a couple of things after I put up this PR so I wanted to raise them here and get your opinions:

1. According to the current implementation in this PR, the changelog.yml file must go at the root folder of the package. I also considered adding it to the docs folder but decided against it as I thought we should keep the docs folder for any human-readable formats like .md. I can imagine, in the future, elastic-package build generating a docs/changelog.md file from changelog.yml if we have a use case for it.

2. According to the current implementation in this PR, the changelog.yml file contains changes for all versions of the package. An alternative approach would be for the changelog.yml file to contain changes only for the current version of the package. This would have some advantages and disadvantages:

   • Advantage: every package version does not have to contain it's own changelog entries and also changelog entries from past package versions. If a package is released frequently, the changelog.yml in each subsequent version would not grow larger and larger over time.
   • Advantage: the package author would not need to repeat the version in the changelog.yml from the manifest.yml. We can simply assume that the contents of changelog.yml apply to the version mentioned in the manifest.yml.
   • Disadvantage: when bumping up a package version, the package author would need to remember to clear out the existing changelog.yml and start with a clean slate for the new version.
   • Disadvantage: not sure if this is a disadvantage per se, but if a client (e.g. the Fleet UI) wants to consume the entire set of changes between two versions of a package or for all versions of a package, we would need a mechanism to stitch together changelogs from individual package versions into a larger list. This could be done via a new Package Registry API.

[mtojek]

According to the current implementation in this PR, the changelog.yml file must go at the root folder of the package. I also considered adding it to the docs folder but decided against it as I thought we should keep the docs folder for any human-readable formats like .md. I can imagine, in the future, elastic-package build generating a docs/changelog.md file from changelog.yml if we have a use case for it.

Most likely it's personal preference, but it's easier to find if there is a changelog package if it's in the root, close to the README.md. I'm fine with other solution too (put it in docs/).

According to the current implementation in this PR, the changelog.yml file contains changes for all versions of the package. An alternative approach would be for the changelog.yml file to contain changes only for the current version of the package. This would have some advantages and disadvantages:

I think it might be easier to keep the changelog file additive and don't clean it before releases. Actually it might be convenient not to jump over versions to check when a feature has been released.

[ycombinator]

Thanks for the feedback, @mtojek. Based on it, I'm going with the changes in this PR as-is.

[ruflin]

Thanks for getting this in. Looking forward to see this showing up in the packages.