Release Strategie

[flochaz]

What release strategy do we want to follow ?

• Do we want on pre release
  • to have package published to npm ?
  • to have doc published ?
    • under main ?
    • under package beta version ?
  • to have package.json bumped ?
  • ...

(I personally answered in my proposal 1)

Current flow

Pre release

• trigger: On merge to main - (on-release.yml : thanks to npx lerna version --conventional-commits --conventional-prerelease --preid test --create-release github --force-publish=* --yes)
• Github commit:
  • commit created with
    • git tag with preid beta (0.2.0-beta.10)
    • package.json version bumbed with preid beta (0.2.0-beta.10)
    • changelog.md: extra line with changes merged

    # [0.2.0-beta.11](https://github.com/awslabs/aws-lambda-powertools-typescript/compare/v0.2.0-beta.10...v0.2.0-beta.11) (2021-12-28)
    
    
    ### Bug Fixes
    
    * Remove publishing doc on `develop` version and fix missing leading 0 in version ([#356](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/356)) ([44991bc](https://github.com/awslabs/aws-lambda-powertools-typescript/commit/44991bcdf0842274333928da3cc12052624808eb))
• Github release: created with preid beta (0.2.0-beta.10) and same data as changelog
• npm: published with preid beta (0.2.0-beta.10) (see https://www.npmjs.com/package/@aws-lambda-powertools/metrics/v/0.2.0-beta.10)
• Doc: published under preid beta (0.2.0-beta.10) (see https://awslabs.github.io/aws-lambda-powertools-typescript/0.2.0-beta.10/)

Release

No Release workflow in place

Proposal 1

Pre release

• trigger: On merge to main
• Github commit:
  • commit created with
    • No tag
    • package.json version: bumbed with preid dev (0.2.0-dev.10)
    • changelog.md: adding Unreleased section only with lerna-changelog --from=$(git describe --tags `git rev-list --tags --max-count=1`)
• Github release: Draft created or updated if exists by release drafter
• npm: NONE
• Doc: published under dev (see https://awslabs.github.io/aws-lambda-powertools-typescript/dev/)

Release

• trigger: manually
• Github commit:
  • commit created with
    • git tag 0.2.0
    • package.json version bumbed 0.2.0
    • changelog.md: extra line with changes merged

    # [0.3.0](https://github.com/awslabs/aws-lambda-powertools-typescript/compare/v0.1.0...v0.2.0) (2021-12-28)
    
    ### Bug Fixes
    
    * Remove publishing doc on `develop` version and fix missing leading 0 in version ([#356](https://github.com/awslabs/aws-lambda-powertools-typescript/issues/356)) ([44991bc](https://github.com/awslabs/aws-lambda-powertools-typescript/commit/44991bcdf0842274333928da3cc12052624808eb))
• npm: published (0.3.0)
• Doc: published under (0.3.0)
• Github release: MANUALLY move from draft to actual release using latest tag (after publish)

[saragerion]

Thanks Florian! cc: @heitorlessa

[ijemmy]

I'm happy with almost everything in proposal 1. Two points I'd like to discuss:

1. Can we NOT publish doc with beta version in pre release. We'll pollute our doc version dropdown very quickly.

Instead, we can use main version (similar to develop in Python power tool) to get the latest version in beta. If anyone wants a specific version of doc, they can check out and run mkdocs locally.

2. In Release process, should we manually edit the Github release after the workflow?

From DX perspective, CHANGELOG.md is auto-generated. Though we have reviews, the PR name might not be descriptive enough. So we may need to manually edit it after the workflow.

Ideally, I would love to have RELEASE_NOTE.md that is committed in the repo and use content from there. But I am not sure how much lerna version can be tweaked.

[flochaz]

I'm happy with almost everything in proposal 1. Two points I'd like to discuss:

1. Can we NOT publish doc with beta version in pre release. We'll pollute our doc version dropdown very quickly.

Instead, we can use main version (similar to develop in Python power tool) to get the latest version in beta. If anyone wants a specific version of doc, they can check out and run mkdocs locally.

indeed agree. I modified the proposal accordingly.

2. In Release process, should we manually edit the Github release after the workflow?

From DX perspective, CHANGELOG.md is auto-generated. Though we have reviews, the PR name might not be descriptive enough. So we may need to manually edit it after the workflow.

Ideally, I would love to have RELEASE_NOTE.md that is committed in the repo and use content from there. But I am not sure how much lerna version can be tweaked.

I would personally prefer we force ourself to put meaningful PR titles and don't do manual update. If it's manual with simply have to add --no-changelog and nothing will be generated then we can manually commit whatever we want (CHANGELOG.md and/or RELEASE_NOTES.md)

[saragerion]

I agree 100% with the meaningful PR titles.
A possible action point here to "mitigate" this aspect of the PR titles is to make this etiquette more explicit in our contributing guidelines:
#115 (comment)

Parallel to this, I also agree with the fact that more meaningful release notes are appreciated by our AWS community.

So for the "release" phase: what about still using automation to publish a release notes draft with the list of all the changes as we do now, and then have a human make them more readable and elaborated and publish it: https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#creating-automatically-generated-release-notes-for-a-new-release

[heitorlessa]

Ideally, I would love to have RELEASE_NOTE.md that is committed in the

repo and use content from there. But I am not sure how much lerna version can be tweaked. Have you folks considered using GitHub Release instead? It *1/ *auto-tags the latest commit with a given version if one doesn't exist, *2/* exposes the version released for any GitHub Actions workflow under published event, and *3/* and most importantly you get a chance to provide human updates instead of dumping commits/PRs - we also have Release Drafter bot that categorises PRs based on labels & shout out to collaborators, so you can do minor tweaks before publishing it. One of my personal challenges with fully automated projects is the lack of information of what's actually in a release - it has less to do with the desire to automate and make releases boring (a great thing!) but more on forgetting the communication, marketing, and community aspect of it. You can keep proposal 1 while keeping the release note as if you had a What's New customers, dependabot & social media can link to.

…

On Wed, 29 Dec 2021 at 14:33, Florian Chazal ***@***.***> wrote: I'm happy with almost everything in proposal 1. Two points I'd like to discuss: 1. Can we NOT publish doc with beta version in *pre release*. We'll pollute our doc version dropdown very quickly. Indeed agree — Reply to this email directly, view it on GitHub <#366 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAZPQBA7HZYJEVCTHC3G73LUTMEZHANCNFSM5K5X4G2A> . You are receiving this because you were mentioned.Message ID: <awslabs/aws-lambda-powertools-typescript/repo-discussions/366/comments/1883269 @github.com>

[flochaz]

Maybe an easy way to do this then is to not push the changelog auto generated commit but go through a PR (created by the github action) which can be easily be modified if manual intervention is needed ?

[dreamorosi]

I agree that there's value in having properly articulated release notes, Heitor is been doing this & people seem to be appreciating it (see screenshot below about a tweet about this):

I'm not sure what's the best way to achieve it but ideally I'd go with Proposal 1 but still have a way of manually curating the release notes in case we want to add something like a screenshot or additional details.

Finally, I think that for when we'll have (hopefully!) external contributors giving them a shout out in the release notes is a really good thing for engagement as they'll have their name up there and might be encouraged to keep contributing and/or sharing the new release on their social media/circles.

[flochaz]

Can't argue against that :)

[saragerion]

+1 on release drafter proposed by @heitorlessa . We can still use automation to create a draft with a list of changes, and then publish the human readable version.
See some thoughts here:
#366 (reply in thread)

[flochaz]

From yesterday discussion:

• On merge to main
  • We don't
    • publish to npm
    • publish github on intermediary commits
    • tag bump commit
  • We bump intermediary (prerelease) versions (each merge to main) with dev pre-id
  • We add [Unreleased] entry in changelog with everything that changed since last tag
• On manually triggered release action
  • We bump versions with beta pre-id during beta phase

[flochaz]

lerna version won't let us add a pre-id for release. So, 2 options:

1. to not bump version on "merge to main" and only update changelog with unreleased
2. don't add pre-id on release and follow semantic versioning by assuming 0. means not stable

[saragerion]

I am ok with option 1

[saragerion]

This will be closed, the only pending decision is on the frequency.