Create changes file

[Jessie212]

@ebyhr What would you like me to do about the previous versions? Should we just mention that features from all the releases are documented in the README?

[mosabua]

We are adding this file as suggested by you since there was no other release notes list. We pulled the info from the announcements on slack. The proposed process changes is to just update this file prior to each release manually. Then each tag has the latest info in it and master branch also has it readily available. We can then link to this document from other sources that want to refer to specific releases or the changes in general.

[hashhar]

So something similar to how https://github.com/airlift/airbase handles release notes. Every PR that is a user facing change also adds changes to CHANGES.md? This makes sense to me.

The Slack announcements are a cherry-picked listing of "some impactful" changes - they aren't exhaustive and listing them in a formal changelog would be slightly misleading.

We can start with current release.

[hovaesco]

FYI we recently introduced changie in dbt-trino https://github.com/starburstdata/dbt-trino/pull/98 (and other useful stuff like linting, formatting etc.). It automates creating of CHANGELOG.

[leniartek]

@mosabua Going forward we will automate change log creation as we did in dbt-trino https://github.com/starburstdata/dbt-trino/blob/master/CHANGELOG.md

I don't mind adding the past release notes manually if you want to.

[mosabua]

okay ... then we can close this PR maybe? Either way .. just let us know when that page is up..

[hashhar]

@leniartek That release notes page has some issues - the people who contribute changes shouldn't be the one contributing release notes. It needs an editorial process. As an example none of the "features" mentioned in the release notes mention how to opt into or use that feature. Same for bugs - they don't say when or how could it be encountered.

We should involve @mosabua / @colebow for the initial process and leverage their help to see what parts can and cannot be automated.

[mosabua]

Is there any progress on how you want to proceed @leniartek @hovaesco @hashhar and others?

[hashhar]

@mosabua I'm in favour of the approach proposed here because the people writing release notes should not be same as the one who added the feature since it leads to pointless changelogs (see the example in my comment above).

[hashhar]

I'll merge this PR but I still think we should not document past releases since those release notes are not complete and only a highlight of select features from a release.

[hovaesco]

I would argue that it leads to pointless changelogs since it comes within PRs, so maintainer can review it, suggest rewording, propose something different etc.

I'm fine with whatever approach which will improve the quality of delivering new releases. We all see a need of having release notes, so let's just figure out who will be responsible for maintaining them and what process we can follow.

[hovaesco]

I've opened a PR which adds a pull request template, since we should follow the same process as in Trino project. https://github.com/trinodb/trino-python-client/pull/234

[mosabua]

So I think we need to decide how to proceed. If we follow the same approach as in trino, then we would merge the PR template, merge this PR, and then create a PR that updates the info for the next release. Then keep updating that PR and merge it just before release.

We are happy to help with this implementation just like we do in Trino .. if you are happy to go down that route.

One thing we would have to decide is if we use this current content and just get better... or if we start with zero info. Personally I think some release notes (like in this PR) are better than none .. but YMMV

[hashhar]

So I think we need to decide how to proceed. If we follow the same approach as in trino, then we would merge the PR template, merge this PR, and then create a PR that updates the info for the next release. Then keep updating that PR and merge it just before release.

Yes. That makes sense. We want to start a process similar to Trino for now and we can see what can be improved over time.

We are happy to help with this implementation just like we do in Trino .. if you are happy to go down that route.

Thank you.

One thing we would have to decide is if we use this current content and just get better... or if we start with zero info. Personally I think some release notes (like in this PR) are better than none .. but YMMV

I tend to think that starting with no information is better since the current release notes are just some selected highlights and slightly misleading (since they are not complete). But I'm with either.

[hashhar]

Ping @colebow to acknowledge since we'd need his help as well. I'll merge this then.

[colebow]

Ping @colebow to acknowledge since we'd need his help as well. I'll merge this then.

Happy to help in whatever way is needed.

[hashhar]

Thanks @colebow. I'm merging this PR - the process is similar to what we do in Trino.

• Each PR (at-least recently opened ones) will have a release notes in PR template.
• We keep a PR open with draft release notes - in CHANGES.md added in this PR
• Before a release is cut we review and merge CHANGES.md
• Perform a release and announce.

[mosabua]

Can we get this merged and then do an update to the new release in a follow up PR? @Jessie212 is unavailable this week

[hashhar]

Thanks @Jessie212 and others for contributing this and helping make sure future versions come with release notes.