Add automation

[jcbhmr]

trafficstars

Original issue

GitHub Actions can do a lot of magic stuff for you! Here's some things that a lot of npm packages have that might be interesting to add to this project:

1. A test workflow that runs npm test on each Node LTS version
2. A publish workflow to auto run npm publish with an npm token on each release

Things to automate:

• [ ] Make it so that creating a GitHub Release does these things:
  • [x] Publish to https://www.npmjs.com/ using npm publish
  • [ ] Publish to https://deno.land/x using another deno/-prefixed release tag on a build branch
  • [x] Deploy the typedoc generated documentation website to GitHub Pages
• [ ] Make it so that PRs have the following tests run against them:
  • [x] Run npm test on Node.js LTS versions
  • [ ] Make sure that the package.json version property has changed
• [ ] Make it so that PRs that change documentation-related things have a preview artifact that you can inspect

[mesqueeb]

@jcbhmr i'd love to add some automation! the thing is i just didn't spend the time yet into looking into everything that's possible and how to actually set everything up. I set up Github Actions for my main project for work and I must say it has been such a time-suck and keeps putting me into tooling hell without making any actual progress on the actual codebase that I've been rather reluctant into introducing it into smaller npm packages. 😅

That being said, if you are able to set up some small & low-maintenance Github Actions then I'm very open to merging that PR!

[jcbhmr]

I note that you mentioned you want to keep this package relatively simple. I personally find the "dev" "production" branches highly confusing and over-complicated for what I assumed was the basic workflow of:

1. develop stuff in branches
2. merge those into main
3. every so often tag main as a vN.N.N release
4. releases trigger npm publish and github pages

Would it be worthwhile to either simplify/normalize this process and/or document it somewhere as to how your package management & release workflow works? I usually do a "development" blurb section in my readmes like this:

[jcbhmr]

I also think that removing dist from source control is a good step to simplify the workflow of stuff too. That way you don't need to commit your build artifacts, you just generate those in the publish.yml workflow when running npm publish or npm test or whatever. Leave the compilation artifacts out of CI seems to be the trend in other npm packages. This is relatively simple to do since we almost already have it! #41

[jcbhmr]

offtopic: Another thing is potentially splitting each function into its own file. This would definitely encourage more writing in the JSDoc area since it's like "I need to write more stuff to fill my IDEs text page, thus I will write more JSDoc examples". I don't think this would impact the tree-shakability of the package at all. You just need a barrel export index.ts and you're good to go! 😊 #45

[mesqueeb]

I note that you mentioned you want to keep this package relatively simple. I personally find the "dev" "production" branches highly confusing and over-complicated for what I assumed was the basic workflow of:

1. develop stuff in branches
2. merge those into main
3. every so often tag main as a vN.N.N release
4. releases trigger npm publish and github pages ...

before I was thinking I'd need to have a production and dev branch separate so I can merge everything from dev into production once I wanna do a release. It would auto-bump the package version and publish to npm. I already have a bump workflow from other projects I could use for this.

However, I then came to the realisation I just execute npm run release which uses np to publish: https://github.com/sindresorhus/np

this is actually a pretty great CLI experience where you can choose the bump type, then it bumps for you, but it also auto creates the tag & creates a release on github releases with a list of all the commits included in that release, these: https://github.com/mesqueeb/is-what/releases

The publish workflow we recently added now will just fail because I use np to release. I'm thinking that we should only start using the workflow to publish if it can do these extra things:

• it should auto bump the package, it could perhaps look at breaking:/feat:/fix: commit tags for determining the bump type
• it should auto create a tag & sync that to github
• it should auto create the release notes with the commits included to github releases

[mesqueeb]

I also think that removing dist from source control is a good step to simplify the workflow of stuff too. That way you don't need to commit your build artifacts, you just generate those in the publish.yml workflow when running npm publish or npm test or whatever. Leave the compilation artifacts out of CI seems to be the trend in other npm packages. This is relatively simple to do since we almost already have it! #41

I personally don't mind it. I don't see any downsides tbh. What do build artifacts have as downsides you reckon?

I like to be able to see what changes to the build pipeline actually change in the dist folder. I also like how easy it is for other devs to browse the dist files from github, without needing to clone, install and build.

[jcbhmr]

before I was thinking I'd need to have a production and dev branch separate so I can merge everything from dev into production once I wanna do a release. It would auto-bump the package version and publish to npm. I already have a bump workflow from other projects I could use for this.

I guess. it's a bit complicated for a 1-and-a-half person project tho. You only do this release like, what, once every week max? ⏳

However, I then came to the realisation I just execute npm run release which uses np to publish: https://github.com/sindresorhus/np

this is actually a pretty great CLI experience where you can choose the bump type, then it bumps for you, but it also auto creates the tag & creates a release on github releases with a list of all the commits included in that release, these: https://github.com/mesqueeb/is-what/releases

For projects like this (i.e. you don't release more than once per day) I think are just fine with a workflow like this:

1. branch off main
2. do code
3. merge back to main with version bump
4. merge more stuff into main
5. main is now 20 commits ahead with a minor change
6. right before you do the "draft new Release" in GitHub UI you check the package.json version to sanity-check it
7. you write release notes like "make sure you do this now!" or similar
8. you autogen the PR release notes
9. you click release
10. auto-ci runs npm publish with the new version from main that you just bumped manually
11. you're done

You'll note that this is somewhat manual. That's OK. The time tradeoff of making tags and conforming PR commit messages, etc. is overkill when you aren't releasing frequently and you're team is small enough to know roughly what's going on. If this were a 50k line codebase with 10 members then yes automatic release bumping would be critical. 😆

bottom line: If you really want that automatic release thing (merge PR = release) then be warned that it's a bit more work and complexity! I think that's kinda against what you said 😂

i'd love to add some automation! I must say it has been such a time-suck and keeps putting me into tooling hell

I think that a basic on-release trigger so that Releases are your main interface into the npm publish-ing workflow is a good idea. Avoid manual npm publish IMO; do your releases via GitHub Releases! 😊

The publish workflow we recently added now will just fail because I use np to release. I'm thinking that we should only start using the workflow to publish if it can do these extra things:

• it should auto bump the package, it could perhaps look at breaking:/feat:/fix: commit tags for determining the bump type
• it should auto create a tag & sync that to github
• it should auto create the release notes with the commits included to github releases

Why not the reverse? 🤔 Create a GitHub Release and everything else cascades after that?

[jcbhmr]

I like to be able to see what changes to the build pipeline actually change in the dist folder. I also like how easy it is for other devs to browse the dist files from github, without needing to clone, install and build.

I think if you really want this you can use https://github.com/actions/upload-artifact with npm pack and get the .tar.gz that would have been published as a build artifact you can inspect!

[jcbhmr]

Guess what! 🥳 I found a pretty good workflow that I think ticks all (most) the boxes for the version thing!

1. It's medium-ish automation. It's another check-version-bump.yml or similar 🤷‍♂️ but it's relatively simple!
2. It makes you bump the version in PRs if you touch certain code bits!

https://github.com/del-systems/check-if-version-bumped

- uses: del-systems/check-if-version-bumped@v1

That way when you open a PR that matches *the patterns* for Node.js source code, it'll trigger this job to check the package.json bumping.

🛑 CAVEAT: It doesn't know if the change was major, minor, or patch; it just wants the version to be bumped! This is good enough for ALMOST EVERYTHING since the main thing you want to prevent is the classic: "I forgot to bump the version in the PR..." mistake! 🤣