infra: #197/#240 create release using workflows #289

thompson-tomo · 2025-12-06T01:58:30Z

Avoids #197 and #240 being an issue going forward and resolves if maintainer steps below are done.

This introduces github workflow for managing releases. This workflow is triggered when a tag is added to a commit and performs the following:

Set npm package version based on tag value
Create npm package
Uploads npm package to npm
Create github release with npm package attached and auto generated release notes

Required steps by maintainers to enable closure of the 2 issues:

Add 2.2.1 tag to commit bb82960 -> Needed for version mismatch between npmjs and github #240
Setup trusted publishers https://docs.npmjs.com/trusted-publishers/
Go to github tags and starting from 1.0.0 create a release for each tag by clicking the following option:

followed by the create release notes option:

-> Needed for #197

thompson-tomo · 2025-12-09T12:54:28Z

@PeterDaveHello / @AndrewSouthpaw / @thlorenz thoughts on automating the release process including release note generation?

Note the manual steps to generate old release notes described in description.

PeterDaveHello · 2025-12-28T08:14:38Z

package.json

  "name": "doctoc",
  "description": "Generates TOC for markdown files of local git repo.",
-  "version": "2.2.0",
+  "version": "0.0.0-development",


I'm not sure if this is a good idea, as based on my limited experience with Node.js app development, it doesn't appear to be a common practice.

For me it is better and more efficient to use a clear placeholder value rather than having to either manually maintain the version value or adding more advanced ci pipelines given low volume of releases. Note this value is used purely for informational purposes as the git tag value is used to ensure they are aligned.

I don't love this either. It's standard practice for the "version" tag to accurately reflect the npm and git tags. Not having that can break standard expectations.

What would it take to include bumping the version tag here?

That is still the case that the package version & git tags all match because at build time the value of the tag is set as the value. This means as a user they see no difference.

The difficulty is if we have the trigger of a release being that a tag is added, how can we get that value to be set in the source code so that it matches. It would mean the tag is 1 commit behind.

The common way to do it would be to raise a pr which bumps the version and when merged the release occurs. That would be a big change for such infrequent releases.

Ah, ok. I'm fine with it then as long as the end result has them match.

I would've gone the route of raising a PR to bump the version anyway, but this is good enough, and as you said the releases aren't that frequent.

Can you add some notes to the release.yml summarizing the tradeoffs and link to this discussion?

I have added some comments and will add them here if happy.

Copilot

Pull request overview

This PR introduces automated release management through GitHub workflows to prevent manual release inconsistencies. The workflow triggers on version tags and automates npm package publishing and GitHub release creation.

Key changes:

Sets package.json version to development placeholder to be updated by workflow
Adds GitHub workflow that publishes to npm and creates releases on tag push
Requires maintainer setup of npm trusted publishers and retroactive release creation

Reviewed changes

Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.

File	Description
package.json	Version changed to development placeholder for workflow automation
.github/workflows/release.yml	New workflow automating npm publish and GitHub release on version tags

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

.github/workflows/release.yml

Co-authored-by: Copilot <[email protected]>

Copilot

Pull request overview

Copilot reviewed 2 out of 3 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

.github/workflows/release.yml

Copilot · 2025-12-28T19:48:27Z

.github/workflows/release.yml

+      - run: npm publish
+
+      - name: Release
+        if: ${{ always() }}


Using always() condition means the release will be created even if npm tests fail or npm publish fails. This could result in GitHub releases for code that failed testing or wasn't successfully published to npm. Consider using if: success() instead to only create releases when all previous steps succeed.

Suggested change

if: ${{ always() }}

if: ${{ success() }}

Agree this should ideally be changed but will wait for after trusted publishing has been confirmed as we want for the time being that if npm upload fails the artifact's is still on the github release.

Sounds good. Trusted publishing is confirmed.

.github/workflows/release.yml

Co-authored-by: Copilot <[email protected]>

.github/workflows/release.yml

AndrewSouthpaw · 2026-01-14T04:24:47Z

package.json

  "name": "doctoc",
  "description": "Generates TOC for markdown files of local git repo.",
-  "version": "2.2.0",
+  "version": "0.0.0-development",


I don't love this either. It's standard practice for the "version" tag to accurately reflect the npm and git tags. Not having that can break standard expectations.

What would it take to include bumping the version tag here?

Co-authored-by: Andrew Smith <[email protected]>

thompson-tomo · 2026-01-28T00:27:31Z

@AndrewSouthpaw how can we continue moving this forward as I am keen to get a release of both libraries to unblock other projects ie otel I contribute to.

AndrewSouthpaw

Just a couple final notes and we're good to go! Thanks for your patience, I was on vacation (again, I've been unemployed and enjoying the time away from a computer).

thompson-tomo · 2026-01-28T16:46:46Z

Thanks for the update Andrew. No worries, I have made the changes in the other repo and will add them here once it is merged. 🙂 also thank you for being willing to review/merge the pr's. 👍

AndrewSouthpaw · 2026-01-29T14:54:34Z

Happy to do it. I know from experience that dealing with slow-moving-but-popular repos can be a pain, and I appreciate your persistence in poking us! As long as you keep @'ing me, it'll show up in my email and I'll try to be more consistent reviewing your PRs. 😄

AndrewSouthpaw

This looks good! I'll go ahead and leave this unmerged for you to backport the comments and then I'll land this one too.

Added issue creation step for npm publish failures.

thompson-tomo · 2026-01-29T15:20:28Z

Sure thing, will keep that in mind and keep trying to keep them small. Note I have been trying to clean things up hence the updating/closing out of old issues/pr's and why I raised #303 today.

The workflow changes have been brought across and should be mergable now.

AndrewSouthpaw · 2026-01-29T15:46:34Z

.github/workflows/release.yml

+      - run: npm publish
+
+      - name: Release
+        if: ${{ always() }}


Sounds good. Trusted publishing is confirmed.

thompson-tomo force-pushed the infra/#240_CreateRelease branch 6 times, most recently from 8de0aa1 to c1be012 Compare December 6, 2025 02:16

thompson-tomo changed the title ~~Infra: #197/#240 create release using workflows~~ infra: #197/#240 create release using workflows Dec 7, 2025

thompson-tomo added 6 commits December 8, 2025 12:42

Auto create release on version tag

d55234f

Add package to release

f15fe70

feat: auto version and publish to registry

50a7993

feat: always run release step

30bdb97

linting

eda578f

Update release.yml

2935046

thompson-tomo force-pushed the infra/#240_CreateRelease branch from 7247e50 to 2935046 Compare December 8, 2025 01:42

Simplify npm publish command in release workflow

e42c18b

thompson-tomo force-pushed the infra/#240_CreateRelease branch 2 times, most recently from a0f8d6b to de1bab5 Compare December 26, 2025 01:23

typo fix

dc354bf

thompson-tomo force-pushed the infra/#240_CreateRelease branch from de1bab5 to dc354bf Compare December 26, 2025 01:24

PeterDaveHello reviewed Dec 28, 2025

View reviewed changes

PeterDaveHello requested a review from Copilot December 28, 2025 08:14

Copilot AI reviewed Dec 28, 2025

View reviewed changes

.github/workflows/release.yml Outdated Show resolved Hide resolved

.github/workflows/release.yml Show resolved Hide resolved

.github/workflows/release.yml Outdated Show resolved Hide resolved

thompson-tomo and others added 2 commits December 28, 2025 19:20

Update release.yml

07555c5

Co-authored-by: Copilot <[email protected]>

Update release.yml

c379803

PeterDaveHello requested a review from Copilot December 28, 2025 19:48

Copilot AI reviewed Dec 28, 2025

View reviewed changes

Update release.yml

a7b934f

Co-authored-by: Copilot <[email protected]>

thompson-tomo mentioned this pull request Jan 13, 2026

infra: CI manages release process thlorenz/anchor-markdown-header#58

Merged

AndrewSouthpaw requested changes Jan 14, 2026

View reviewed changes

Update release.yml

3020c35

Co-authored-by: Andrew Smith <[email protected]>

AndrewSouthpaw reviewed Jan 28, 2026

View reviewed changes

AndrewSouthpaw approved these changes Jan 29, 2026

View reviewed changes

Enhance release workflow with issue creation on failure

9100857

Added issue creation step for npm publish failures.

AndrewSouthpaw approved these changes Jan 29, 2026

View reviewed changes

AndrewSouthpaw merged commit bbe3b17 into thlorenz:master Jan 29, 2026
5 checks passed

Uh oh!

infra: #197/#240 create release using workflows #289

infra: #197/#240 create release using workflows #289

Conversation

thompson-tomo commented Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

thompson-tomo commented Dec 9, 2025

Uh oh!

PeterDaveHello Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

thompson-tomo Dec 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AndrewSouthpaw Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

thompson-tomo Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

AndrewSouthpaw Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thompson-tomo Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Dec 28, 2025

Choose a reason for hiding this comment

Uh oh!

thompson-tomo Dec 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AndrewSouthpaw Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AndrewSouthpaw Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

thompson-tomo commented Jan 28, 2026

Uh oh!

AndrewSouthpaw left a comment

Choose a reason for hiding this comment

Uh oh!

thompson-tomo commented Jan 28, 2026

Uh oh!

AndrewSouthpaw commented Jan 29, 2026

Uh oh!

AndrewSouthpaw left a comment

Choose a reason for hiding this comment

Uh oh!

thompson-tomo commented Jan 29, 2026

Uh oh!

AndrewSouthpaw Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

thompson-tomo commented Dec 6, 2025 •

edited

Loading

thompson-tomo Dec 28, 2025 •

edited

Loading

AndrewSouthpaw Jan 28, 2026 •

edited

Loading

thompson-tomo Dec 28, 2025 •

edited

Loading