[spike] - automate changelog with changie

[emmyoop]

resolves #4652

Description

Add changie to automate CHANGELOG generation.

This PR creates a fake 1.1.1 release. Look through commits to see the steps that get taken while creating the CHANGELOG itself.

changie Workflow

1. Make changes in branches. run changie new to create a yaml file that holds the info needed to generate the changelog line. Merge your branch in.
2. changie batch 1.1.1 when ready to create your release. This deletes all the yaml files and combines them into a single markdown file.
3. changie does not currently have the ability to generate footer sections (our Contributors) so you have to run scripts/add-contributors.py to generate that section. You can also directly modify the markdown file if needed. This will not break anything.
4. Run changie merge to merge that markdown file into the existing CHANGELOG.

Checklist

• I have signed the CLA
• I have run this code in development and it appears to resolve the stated issue
• This PR includes tests, or tests are not required/relevant for this PR
• I have updated the CHANGELOG.md and added information about my change

[emmyoop]

There's a PR currently out for changie to add header/footer sections that we should be able to use for the Contributors section. See #233

[jtcohen6]

This is super cool! I took it for a spin locally, and found it quite simple to use :) None of my comments below should be considered as blocking our adoption of changie / this overall approach.

With external contributors in mind:

• I think we'll need a more detailed update to PR template + CONTRIBUTING.md docs
• The CLI prompt with changie is very cool, but I'm wondering — do we need contributors to actually install changie themselves? Can we just keep around a "sample" change file )(.changes/sample_change.md) that they can copy/paste/update? The only risk is, it's unlikely users would manually update the time field, so chronological ordering may not be totally right

changie batch 1.1.1 when ready to create your release. This deletes all the yaml files and combines them into a single markdown file.

To ask a favorite question: How do we handle backports? If I'm following right, we:

• Create a change file (changie new) for the fix
• Backport the fix along with its change file
• Generate a new changelog (changie batch) on the main branch for the next minor version, and on the 1.x.latest branch for the next patch version
• Upshot: the change is included in both versions, and its changelog entry is reflected in both places

To date, my personal habit when backporting has been to add its changelog entry under the patch release only—the implication being, a v1.0.x patch fix will also be included in v1.1.0. I'm ok with this shift, to "double-entry bookkeeping." A consistent adoption of either approach is preferable to inconsistency, which is what we have today.

Only thing worth calling out: Patch release notes / changelog entries will only be reflected on the 1.x.latest branches. The main branch entries will only reflect minor versions. I suppose we add some handling for that in our "big" CHANGELOG.md reconciliation process...?

changie does not currently have the ability to generate footer sections (our Contributors) so you have to run scripts/add-contributors.py to generate that section.

🤞 for miniscruff/changie#233!

You can also directly modify the markdown file if needed. This will not break anything.

honestly, this is very reassuring :)

[jtcohen6]

Suggested change

	- label: Dependancies
	- label: Dependencies

[jtcohen6]

Now that we have this capability, I like the idea of batching changelog entries in a few different ways:

1. Version-specific changelogs, which also go in GitHub release notes for each prerelease
2. A "combined" changelog for each final release, that batch changes from all prereleases (e.g. v1.1.0b1 + v1.1.0b2 + v1.1.0rc1 = v1.1.0 [final]) — this should go into the final version's release notes
3. A full "combined" changelog, to live continually at CHANGELOG.md

To that end, changie batch gets us the first, and we should be able to write some dead-simple scripts that get us 2 + 3, by combining the components produced by (1)

[miniscruff]

Hey I found this thread as it was linked to the changie PR above and want to give my two cents. Changie currently has no way of specifying something as pre-release, alpha or similar. My recommendation would be to use the changie batch --keep option and move the yaml files into a separate folder before release. Then when the final version is ready, move all the yamls back into unreleased and run batch again. Then 3 can be done by doing changie merge.

If this workflow works for you I would be happy to add it to the Changie roadmap as it is a common workflow when using beta and release candidates. Thanks for considering changes and reach out if you need anything else.

[emmyoop]

Would there be value in incrementally rolling up? ie v1.1.0b1 rolls into v1.1.0b2 rolls into v1.1.0rc1 rolls into v1.1.0(final) as opposed to not rolling up until the final release?

changie already has the ability to generate the changelog entry with a --keep flag when running the batch command. That generates the markdown file that can be merged in but does not delete the associated yaml files. You would still need to delete the associate entry from the full cahngelog file with this method though so I'm not sure how much it would save over just have a simple script that could accomplish it for us.

Either way, this makes a lot of sense and would really help clean up our CHANGELOG as it can be confusing now when there are multiple changlog entries under an rc release and non under the final release (ie 0.21.0). Definitely achievable.

[emmyoop]

I'm realizing now rolling up wouldn't be ideal for what gets posted to each individual release. So scratch that.

I think @miniscruff's suggested approach would work nicely for what we need. We can either write a script to automate the process he describes or contribute that change back to changie if @miniscruff is open to that.

[miniscruff]

I don't mind adding it if it works for you, just let me know and I can create an issue for it ( or you can start a discussion for ideas )

[emmyoop]

@miniscruff I would really appreciate if you open an issue for this. It would be a valuable addition for us for sure!

[emmyoop]

Thanks for the feedback @jtcohen6!

Agree 💯 that there needs to be better docs in CONTRIBUTING and the PR template. It would also be valuable to have a github action that ensures a new file has beed added to the /.changes and block merging when it hasn't. That would mean everyone would get a notice when they open a pull request but it's a nice reminder to create that changelog entry.

Creating a template file for Contributors could work but I see two issues:

1. You lose some of the value of changie walking you through creating that changelog entry in a specified format that's easily parseable into the final markdown. We also take on the burden of having to manually make sure things were entered correctly. We then up manually enforcing formatting and syntax which goes against the goals laid out in [CT-115] Automate Changelog #4652.
2. The files are named in very specific ways that changie actually keys off of for building the changelog. File names are composed of the kind (ie, Bug, Under the Hood, etc) and a timestamp. The timestamp is just used for ordering the log entries and is not very high priority but the kind is extremely important in how the logs get built.

Out of curiosity, what is the reluctance in asking our contributors to install changie? His docs are easy to follow and cover all operating systems.

[jtcohen6]

Out of curiosity, what is the reluctance in asking our contributors to install changie? His docs are easy to follow and cover all operating systems.

Just, knee-jerk reluctance to asking anyone to install anything locally if they don't have to? I did find changie very very easy to install :)

Given that contributors are already setting up local dev envs (in most cases), it's hardly much more work.

In addition to a GHA that checks for a new change file—could we even create a GHA that runs changie new, given manual inputs...? Then it's as simple as: Hey, you forgot this, go run it right now.

[emmyoop]

go run it right now.

Interesting for sure! I'll look into it.

Closing this PR as the spike is done. I'll open a new PR soon with the actual implementation and without fake changes.