RFC AWS amplify-js changelog

[modularity]

Motivation

An amplify-js user has two options to decide when and how to upgrade: blindly proceed with a specific version or parse through multiple commits assigned to a given release tag, making it a time consuming and confusing endeavor. Users struggle with upgrading Amplify without full-knowledge of breaking changes or new desirable features.

Proposal

A remedy to this is via clear communication from library contributors to its users. One common way to address this communication issue is with a changelog. This information is often arranged chronologically and assigned tags to reference bug fixes, breaking changes and enhancements. Both users and contributors can reference this document to understand what has notably changed between releases. This allows developers to make smarter decisions in selecting the best version for their project at any given time. Many changelogs also reference GitHub Issues, RFC proposals, feature requests and migration resolution steps. Changelogs provide a birds eye view of where a project has been and where it is going, while acknowledging contributors and fostering its community.

Maintaining changelogs can be automated and rolled into existing release pipelines. It is best to automate this process as much as possible to minimize contributor overhead and promote standardization. One common approach is to leverage commit and/or PR messages tagged on a given release to auto-generate a changelog. This has been used successfully by communities like Rust.

The Amplify-JS team is already using Lerna for monorepo support. There are tools like lerna-changelog that can generate a central changelog to encompass relevant subrepo updates. This could allow each repo to operate independently while ensuring the parent repo can aggregate necessary updates to share with the community.

Existing Implementations

React Native releases - Clever collection of versions along with their respective docs and changelogs.

Rust releases - TLDR with shoutouts on their blog, detailed release notes on repo are auto-generated from code commit messages and contain hyperlinks to relevant resources like GitHub Issues.

Webpack releases - TLDR format on releases page and separate “Full Changelog” with detailed write up and option for community edits.

Release Butler - Engage with community via a Twitter bot that broadcasts your changelog.

Drawbacks & Alternatives

Introducing a changelog takes time and careful planning to configure to the library’s specific needs. While there are many projects that successfully utilize a commit/PR parser for their changelog, the exact implementation and feasibility depends on many factors. This includes the existing tech stack, state of release pipelines, adoption of a new versioning practice along with contributor buy-in, as well as the level of organization and detail desired in the resulting changelog.

Adoption Strategy

Rolling out a robust changelog features like React Native and Rust have may not be realistic on the first iteration. It would be wise to start with an MVP given the existing tech stack with as little friction as possible to existing workflows. Successive iterations can improve the depth and readability of content, integrate with other relevant services like a Twitter bot that broadcasts changelog updates.A carte features can be added as time and demand allow.

[manueliglesias]

Thank you @modularity, this is a very valuable contribution.

Currently, we have some of the required pieces in place (as you pointed out, e.g. lerna). Also, some of the PRs we've merged already make use of commit messages that follow "conventional-commits"

Each package already has CHANGELOG.md file, but currently they have mostly noise. e.g.

https://github.com/aws-amplify/amplify-js/blob/aws-amplify%401.1.19/packages/aws-amplify/CHANGELOG.md

This is great initiative that will roughly require:

• Enforcing the use of commit messages that follow conventional commits (explore use of tools like https://github.com/probot/semantic-pull-requests)
• Improving the release process to not generate CHANGELOG entries for unstable releases.

Please feel free to point missing entries in that lis, I'll be updating it with team feedback too.

[ArmorDarks]

Please, please DO NOT USE automated generation of the changelog from commits. It is useless cancer.

See keepachangelog, section Commit log diffs.

[hoang-innomize]

Personally, I think we should apply this as soon as possible.

I noticed a new release of Amplify today and I am wondering, should I upgrade to latest version to apply some bug fixes and enhancements? I tried to view releases but I cannot find any details about changes have been made for that release. Then I go to issues and try to find what are issues have been fixed on version 1.1.26 (aws-amplify package) and 3.0.1 (aws-aplify-angular), but I cannot find any helpful information as well.

We changed version from 2.1.12 to version 3.0.1, according to Semantic version https://semver.org/, it is a break change version. Is that safe to upgrade?

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[aldegoeij]

@sammartinez when will we have any kind of release notes / changelog on versions?

How can I best figure out what is in a x.x.x.-unstable? Do you have a specific branching strategy?

[dan-rivett]

Any update on this? Be great to have a valuable changelog file similar to the ones already listed at the top of this RFC.

I would also like to see a "Not Yet Released" section in the master version of the file that gets updated as the in-development branch is developed to allow us to see what's upcoming in the next release before it drops.

For example with RN: https://github.com/react-native-community/releases/pull/156/files#diff-4ac32a78649ca5bdd8e0ba38b7006a1e

And React: https://github.com/facebook/react/blob/master/CHANGELOG.md

[mauerbac]

Closing this issue in favor of an implementation across all Amplify repos aws-amplify/docs#3183

[github-actions]

This issue has been automatically locked since there hasn't been any recent activity after it was closed. Please open a new issue for related bugs.

Looking for a help forum? We recommend joining the Amplify Community Discord server *-help channels or Discussions for those types of questions.