Use automation for a changelog and release management #6253

JounQin · 2022-08-11T03:58:09Z

Describe the documentation issue

With https://github.com/changesets/changesets/tree/main/packages/changelog-github, we'll have thanks mentions for contributors in our changelog and releases.

What solution would you like to see?

Enable changesets

Alternative, manage thanks mentions manually.

The text was updated successfully, but these errors were encountered:

ybiquitous · 2022-08-12T15:59:44Z

@JounQin Thanks for the proposal. I have some questions.

We have the following workflow already for updating the CHANGELOG.md file, but will your proposed tool replace with it?

stylelint/docs/maintainer-guide/pull-requests.md

Lines 27 to 32 in 4772851

    
           2. Update the [changelog](https://github.com/stylelint/stylelint/blob/main/CHANGELOG.md) directly via the [GitHub website](https://github.com/stylelint/stylelint/edit/main/CHANGELOG.md) for everything except refactoring and documentation changes: 
        
              1. Create a `## Head` heading if one does not exist already. 
        
              2. Prefix the item with either: "Removed", "Changed", "Deprecated", "Added", or "Fixed". 
        
              3. Order the item within the group by the widest-reaching first to the smallest, and then alphabetically by rule name. 
        
              4. Suffix the item with the relevant pull request number, using the complete GitHub URL so that it works on [the website](https://stylelint.io/CHANGELOG/). 
        
              5. If applicable, lead the item with the name of the rule, e.g. "Fixed: `unit-disallowed-list` false positives for SCSS nested properties".

Can we keep the existing CHANGELOG format with this tool? Because the format change may affect the CHANGELOG page in our website (will permalinks be retained?).
Will this tool affect the existing release workflow with np?

stylelint/docs/maintainer-guide/releases.md

Lines 7 to 17 in 4772851

    
           5. Publish the package to npm and create a GitHub release using [`np`](https://github.com/sindresorhus/np): 
        
              1. [Consistently format](pull-requests.md) the [changelog](../../CHANGELOG.md). 
        
              2. Replace `## Head` with new version number e.g. `## 8.1.2`. 
        
              3. Commit these changes. 
        
              4. Push these changes. 
        
              5. Confirm the changes are correct at [github.com/stylelint/stylelint](https://github.com/stylelint/stylelint). 
        
              6. Run `npm run release`. 
        
              7. Select the version that matches the one from the changelog. 
        
              8. Copy and paste the changelog entries for the published version from [changelog](../../CHANGELOG.md) when the GitHub release page opens. 
        
              9. Confirm the publishing of the package to [www.npmjs.com/package/stylelint](https://www.npmjs.com/package/stylelint). 
        
              10. Confirm the creation of the release at [github.com/stylelint/stylelint/releases](https://github.com/stylelint/stylelint/releases).

If a new tool could reduce the tedious work (e.g. updating the changelog file), that would be great!

JounQin · 2022-08-12T22:32:53Z

We have the following workflow already for updating the CHANGELOG.md file, but will your proposed tool replace with it?

It will.

Can we keep the existing CHANGELOG format with this tool? Because the format change may affect the CHANGELOG page in our website (will permalinks be retained?).

Sure, we can define our own changelog format while keeping previous history changelog unmodified.

Will this tool affect the existing release workflow with np?

We only need to merge a PR like un-ts/prettier#213 for releasing.

ybiquitous · 2022-08-12T22:41:34Z

@JounQin Thanks for the answers. Sounds good to me. 👍🏼

hudochenkov · 2022-08-13T21:57:51Z

We need to consider quality of a changelog before adding any automated tool.

Changelog is one of the most important parts of documentation of any open source project. As I consumer of many open source packages, I've seen lots of changelogs. In my experience automated changelogs usually provide not enough information to the user. Or changelog items are confusing and only make sense to package developers. Or include information, which is not needed to the users (for example dev dependencies updates).

We need to make sure that our changelog provides only needed information and in a good way.

JounQin · 2022-08-13T22:13:12Z

@hudochenkov

Changesets uses user defined changelog, not automated. See also https://github.com/changesets/changesets/blob/main/docs/common-questions.md#common-questions

And its content can always be changed before releasing.

That's why I love it over semantic-release which is very stupid. prettier/prettier-eslint-cli#441

hudochenkov · 2022-08-13T22:41:44Z

@JounQin Do you want to add changesets only for thank you notes?

JounQin · 2022-08-13T22:43:52Z

@JounQin Do you want to add changesets only for thank you notes?

Not at all, It's just a smallest feature of changesets, with changesets we're going to maintain CHANGELOG and releasing much easier.

I'm sorry my issue content could be confusing here.

hudochenkov · 2022-08-13T22:54:07Z

Could you write down what do you want to use changesets for?

How it will change current release flow?

It is important for us to understand everything before time is spent on setting up and configuring new tool.

JounQin · 2022-08-13T23:24:41Z

@hudochenkov OK, let me explain in details.

We'll need to install https://github.com/apps/changeset-bot
We'll need to add https://github.com/changesets/action like https://github.com/un-ts/prettier/blob/master/.github/workflows/release.yml
changesets will handle all CHANGELOG and release related tasks
For instance, a user or maintainer can add a changeset for CHANGELOG via changeset add command, or via GitHub UI like build: languages from package linguist-languages instead un-ts/prettier#212 (comment)
If changesets files exist on the main branch, a PR would be created by GitHub Actions automatically like chore: release package(s) un-ts/prettier#213
We'll need to decide whether to release on CI or manually.
- If we do release on CI, then we'll need to provide a publish input at https://github.com/un-ts/prettier/blob/master/.github/workflows/release.yml#L43 and a NPM_TOKEN secret at https://github.com/un-ts/prettier/blob/master/.github/workflows/release.yml#L46, when we're ready for releasing, we'll only need to merge that PR
- Otherwise, we just don't provide the publush input and NPM_TOKEN secret, and we run npm run release manually, and then copy the correct part of CHANGELOG to draft a GitHub release, see also feat: create GitHub releases on changeset publish changesets/changesets#885

HDYT?

hudochenkov · 2022-08-14T12:18:54Z

Thank you for an explanation!

It might be something interesting to explore. Since I didn't only few releases in the past, I would like to hear from people, who did the most releases: @jeddy3 and @ybiquitous.

ybiquitous · 2022-08-16T01:21:59Z

@JounQin @hudochenkov Thanks for clearing the details!

It seems good to start at a minimum to evaluate the new workflow:

Install https://github.com/apps/changeset-bot
Add https://github.com/changesets/action

We can update CHANGELOG.md automatically via the two things above, right? Additionally, do we need to write a custom formatter to keep the existing CHANGELOG.md format?

If auto-updating CHANGELOG.md will be successful, I think we can move on to further automation.

JounQin · 2022-08-16T01:27:53Z

@ybiquitous

Let's make it work! Feel free to notice me when the GitHub App ready, and then I'm going to raise a PR to enable it in our workflow.

jeddy3 · 2022-08-16T19:05:37Z

It seems good to start at a minimum to evaluate the new workflow:

There's no harm in evaluating a new workflow. Considering we need to be in the terminal for the stylelint-demo and stylelint.io updates anyway, it may prove troublesome to have a different means for releasing Stylelint (and I assume the official configs, and possible all the other packages in the Stylelint org?).

@ybiquitous If you're in favour of evaluating of this workflow then I'm happy to give it ago as you've been doing lots of the releases recently.

ybiquitous · 2022-08-17T00:55:23Z

@jeddy3 Thanks for the feedback. First, I'll try only the changelog automation. Then, if it doesn't fit, let's revert it.

@JounQin I've installed changeset-bot. Could you please open a pull request if you have time?

JounQin · 2022-08-17T01:11:30Z

@ybiquitous I'll raise a PR ASAP.

ybiquitous · 2022-08-21T03:27:07Z

Since there are some problems found in PR #6282, let's try the new workflow in the next iteration (after 14.11.0)!

ybiquitous · 2022-09-18T23:38:52Z

14.12.0 is the first version using the changelog generation! We evaluate that it is easier to update the changelog than before.

But, we encounter a small problem with GitHub Releases. For details, see #6343 (comment)

ybiquitous · 2022-09-28T08:04:28Z

It seems we can now evaluate the new changelog automation workflow. What do you think?

If no objections, we should update the following parts in the maintainer guide:

stylelint/docs/maintainer-guide/pull-requests.md

Lines 27 to 32 in e3421aa

    
           2. Update the [changelog](https://github.com/stylelint/stylelint/blob/main/CHANGELOG.md) directly via the [GitHub website](https://github.com/stylelint/stylelint/edit/main/CHANGELOG.md) for everything except refactoring and documentation changes: 
        
              1. Create a `## Head` heading if one does not exist already. 
        
              2. Prefix the item with either: "Removed", "Changed", "Deprecated", "Added", or "Fixed". 
        
              3. Order the item within the group by the widest-reaching first to the smallest, and then alphabetically by rule name. 
        
              4. Suffix the item with the relevant pull request number, using the complete GitHub URL so that it works on [the website](https://stylelint.io/CHANGELOG/). 
        
              5. If applicable, lead the item with the name of the rule, e.g. "Fixed: `unit-disallowed-list` false positives for SCSS nested properties".

stylelint/docs/maintainer-guide/releases.md

Lines 8 to 12 in e3421aa

    
           1. [Consistently format](pull-requests.md) the [changelog](../../CHANGELOG.md). 
        
           2. Replace `## Head` with new version number e.g. `## 8.1.2`. 
        
           3. Commit these changes. 
        
           4. Push these changes. 
        
           5. Confirm the changes are correct at [github.com/stylelint/stylelint](https://github.com/stylelint/stylelint).

JounQin · 2022-09-28T15:32:57Z

If auto-updating CHANGELOG.md will be successful, I think we can move on to further automation.
-- @ybiquitous

@jeddy3

Do we want changesets to replace np for releasing further on CI? The downside may be mess due to permission of merge/release. Or maybe we just keep it as-is.

ybiquitous · 2022-09-28T16:06:47Z

@JounQin Please let me ask a few questions.

If we publish on CI, will the following 3 to 5 steps no longer be needed?

stylelint/docs/maintainer-guide/releases.md

Lines 13 to 15 in eee9deb

    
           3. Open a terminal window in the `stylelint` repository. 
        
           4. Run `npm run release`. 
        
           5. Select the version from the [`np`](https://github.com/sindresorhus/np) prompt that matches the one in the changelog.

Will changes for the releasing workflow be as follows? (npm run release should run changeset publish, and we should generate a new npm token for publishing)

stylelint/.github/workflows/releasing.yml

Lines 46 to 48 in eee9deb

    
             version: npm run version 
        
           env: 
        
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  version: npm run version
+ publish: npm run release
env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

What will publishing via changeset do? Pushing a Git tag, publishing a new version to the npm registry, and more? (e.g., generating a GitHub release?)

JounQin · 2022-09-28T23:34:59Z

@ybiquitous

Yes, all will be done on CI automatically
Yes
It will push tag, publish npm version and generate GitHub release (But the release content could be different with our format)

ybiquitous · 2022-09-29T00:17:44Z

@JounQin Thanks for the answer.

generate GitHub release (But the release content could be different with our format)

Regarding this, it seems possible to prevent generating a GitHub release via the createGithubReleases: false option of changesets/action.

It sounds good to me to publish on CI for easier workflow, but perhaps it may be tough to recover if a publishing CI job would fail. As of now, we don't have a problem with continuing to use np manually.

JounQin · 2022-09-29T06:53:54Z

it seems possible to prevent generating a GitHub release

Glad to hear

but perhaps it may be tough to recover if a publishing CI job would fail

I'm not sure to understand this part, if the CI job fails, we can just retry it and when the npm version is not published, changesets will still recognize it and try to release again

As of now, we don't have a problem with continuing to use np manually.

Sure, I also don't have a strong opinion on this neither, it just could be a bit redundant to have two release tools while changesets can handle it alone.

ybiquitous · 2022-09-29T07:01:44Z

I'm not sure to understand this part, if the CI job fails, we can just retry it and when the npm version is not published, changesets will still recognize it and try to release again

I'm worried about a situation where tagging is successful but publishing is failed. In such a case, it seems harder to recover than manually releasing. Although, it should be rare.

JounQin · 2022-09-29T07:08:27Z

The order is releasing npm version first, then tag and GitHub release, so I don't think the case would be possible. And also, create/delete a tag/release on GitHub UI is very easy.

ybiquitous · 2022-09-29T07:10:18Z

@JounQin Thanks for the explanation. I understand well. 👍🏼

I'd like to hear @jeddy3's idea.

jeddy3 · 2022-09-29T07:55:59Z

Do we want changesets to replace np for releasing further on CI? The downside may be mess due to permission of merge/release. Or maybe we just keep it as-is.

I think we should keep it as-is as:

during a release, we're in the terminal anyway to perform other updates (e.g. to the website and demo)
our other npm package repos use np

ybiquitous · 2022-09-29T08:07:08Z

during a release, we're in the terminal anyway to perform other updates (e.g., to the website and demo)

That makes sense. I have no objections. 👍🏼

JounQin added the type: documentation an improvement to the documentation label Aug 11, 2022

jeddy3 added status: needs discussion triage needs further discussion and removed type: documentation an improvement to the documentation labels Aug 11, 2022

hudochenkov changed the title ~~Use CI tools like changesets for changelog~~ Use automation for a changelog and release management Aug 14, 2022

hudochenkov added the type: infrastructure an improvement to devops label Aug 14, 2022

ybiquitous added status: wip is being worked on by someone and removed status: needs discussion triage needs further discussion labels Aug 17, 2022

ybiquitous self-assigned this Aug 17, 2022

This was referenced Aug 17, 2022

Introduce changesets for CHANGELOG auto-generation #6274

Merged

Update releasing workflow permission #6281

Merged

ybiquitous mentioned this issue Aug 22, 2022

Add contributors to release note #6297

Closed

ybiquitous mentioned this issue Sep 7, 2022

Stop creating release PR in forked repos #6333

Merged

jeddy3 mentioned this issue Sep 28, 2022

Document pull request and release changes #6369

Merged

jeddy3 closed this as completed in #6369 Sep 28, 2022

ybiquitous mentioned this issue Sep 28, 2022

Automate GitHub Release #6371

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use automation for a changelog and release management #6253

Use automation for a changelog and release management #6253

JounQin commented Aug 11, 2022

ybiquitous commented Aug 12, 2022

JounQin commented Aug 12, 2022

ybiquitous commented Aug 12, 2022

hudochenkov commented Aug 13, 2022

JounQin commented Aug 13, 2022 •

edited

hudochenkov commented Aug 13, 2022

JounQin commented Aug 13, 2022 •

edited

hudochenkov commented Aug 13, 2022

JounQin commented Aug 13, 2022 •

edited

hudochenkov commented Aug 14, 2022

ybiquitous commented Aug 16, 2022

JounQin commented Aug 16, 2022

jeddy3 commented Aug 16, 2022

ybiquitous commented Aug 17, 2022

JounQin commented Aug 17, 2022

ybiquitous commented Aug 21, 2022

ybiquitous commented Sep 18, 2022

ybiquitous commented Sep 28, 2022

JounQin commented Sep 28, 2022 •

edited

ybiquitous commented Sep 28, 2022 •

edited

JounQin commented Sep 28, 2022

ybiquitous commented Sep 29, 2022

JounQin commented Sep 29, 2022

ybiquitous commented Sep 29, 2022

JounQin commented Sep 29, 2022

ybiquitous commented Sep 29, 2022

jeddy3 commented Sep 29, 2022

ybiquitous commented Sep 29, 2022

Use automation for a changelog and release management #6253

Use automation for a changelog and release management #6253

Comments

JounQin commented Aug 11, 2022

Describe the documentation issue

What solution would you like to see?

ybiquitous commented Aug 12, 2022

JounQin commented Aug 12, 2022

ybiquitous commented Aug 12, 2022

hudochenkov commented Aug 13, 2022

JounQin commented Aug 13, 2022 • edited

hudochenkov commented Aug 13, 2022

JounQin commented Aug 13, 2022 • edited

hudochenkov commented Aug 13, 2022

JounQin commented Aug 13, 2022 • edited

hudochenkov commented Aug 14, 2022

ybiquitous commented Aug 16, 2022

JounQin commented Aug 16, 2022

jeddy3 commented Aug 16, 2022

ybiquitous commented Aug 17, 2022

JounQin commented Aug 17, 2022

ybiquitous commented Aug 21, 2022

ybiquitous commented Sep 18, 2022

ybiquitous commented Sep 28, 2022

JounQin commented Sep 28, 2022 • edited

ybiquitous commented Sep 28, 2022 • edited

JounQin commented Sep 28, 2022

ybiquitous commented Sep 29, 2022

JounQin commented Sep 29, 2022

ybiquitous commented Sep 29, 2022

JounQin commented Sep 29, 2022

ybiquitous commented Sep 29, 2022

jeddy3 commented Sep 29, 2022

ybiquitous commented Sep 29, 2022

JounQin commented Aug 13, 2022 •

edited

JounQin commented Aug 13, 2022 •

edited

JounQin commented Aug 13, 2022 •

edited

JounQin commented Sep 28, 2022 •

edited

ybiquitous commented Sep 28, 2022 •

edited