feat: major version tags #682

kanadgupta · 2022-11-29T01:14:28Z

🧰 Changes

I've always really liked how actions/setup-node and actions/checkout use top-level tags for major versions, which are recreated every time there's a tag for that major version. It makes it a lot easier to point to the latest in a workflow (as well as in the docs):

steps:
  - uses: actions/checkout@v3
  - uses: actions/setup-node@v3

We've been shipping a lot of updates lately (a good thing!), but it's gotta be annoying for people that have Dependabot set up, since they're likely using an outdated version already. Now that we have a streamlined release process via npm run bump, I figured we should enhance the process a bit so it automatically recreates a major tag with every release.

As part of this:

I did a bunch of refactoring to try and consolidate our versioning logic as much as possible
I also addressed a little deprecation notice with our GitHub Actions outputs (more details on this in the comments)
This major tag will be surfaced both in our docs and in any workflow files created via our onboarding.

🧬 QA & Testing

I've done a few dry runs of npm run bump and confirmed that the tag is created:

I also tried with a prerelease tag and confirmed that the major tag is not created:

You can follow these steps to try it out yourself:

Check out this branch
Run something like npm run bump -- 8.1.2 or npm run bump -- 8.1.2-beta.0
Inspect the commit created (but do NOT push it) and make sure that everything looks good! Just make sure to delete the tags you create (using git tag -d [tag]) and don't push anything to GitHub.

(fixes RM-4942)

This consolidates getNodeVersion into another file and renames the set-version-output function to have a .js extension so we don't need to have weird `npm run lint` carveouts for it

This pattern for setting outputs is now deprecated

we were previously using a zero-deps approach but now that we need to install deps for the set-version-output step, we might as well use a safer approach here.

this will set up some upcoming tagging changes

This reverts commit 0fc0fe2.

simple-git isn't really being super helpful here, so we might as well use a vanilla node function instead. i struggled to write tests so not gonna use our `getPkgVersion` function either since importing directly from package.json is just fine.

i feel like this flow is better, tagging a beta tripped me up the first time

we should surface the v8 tag in the github actions that we create. this required a decent refactor to consolidate our major version retrieval logic. a bunch of snapshots had to be updated too.

kanadgupta · 2022-11-29T16:44:13Z

bin/set-version-output.js

+  core.setOutput('RDME_VERSION', `v${await getMajorPkgVersion('latest')}`);
+  core.setOutput('NODE_VERSION', getNodeVersion());


The diff got lost in renaming bin/set-version-output to bin/set-version-output.js (which is used for updating the package version in our docs with every sync to main). Two major callouts:

We're now using core.setOutput due to a deprecation notice with the ::set-output technique for setting Actions outputs. It's much cleaner too ✨

We're setting the version in our docs to the major version now (e.g., v8 instead of 8.1.1).

kanadgupta · 2022-11-29T16:46:14Z

documentation/github-actions-docs-example.md

@@ -65,4 +65,4 @@ In the example above, every push to the `main` branch will sync the Markdown con

 > 📘 Keeping `rdme` up-to-date
 >
-> Note that `@RDME_VERSION` (used in the above example) is the latest version of `rdme`. We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/keeping-your-actions-up-to-date-with-dependabot).
+> Note that `@RDME_VERSION` (used in the above example) is the latest version of `rdme`. We recommend [configuring Dependabot to keep your actions up-to-date](https://docs.github.com/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot).


Noticed these links were redirecting, so just fixed them up throughout our docs.

kanadgupta · 2022-11-29T16:47:26Z

package.json

@@ -97,15 +97,16 @@
    "build": "tsc",
    "bump": "npm version -m 'build: %s release'",
    "debug": "ts-node src/cli.ts",
-    "lint": "eslint . bin/rdme bin/set-version-output --ext .js,.ts",


By using the .js file extensions in those bin files, we can omit them from here and they still work as command-line executables. I'm keeping rdme here for now since it's special 💙

kanadgupta · 2022-11-29T16:49:34Z

src/lib/getNodeVersion.js

- *
- * @example 14
- */
-module.exports = function getNodeVersion() {


Moved this function over to src/lib/getPkgVersion.ts¹. We've been keeping this vanilla and as a JS file so we didn't have to install deps prior to syncing our docs, but installing deps has been required for a bit now, so might as well migrate and consolidate.

Footnotes

its test coverage was also moved to __tests__/lib/getPkgVersion.test.ts ↩

kanadgupta · 2022-11-29T16:52:42Z

src/lib/getPkgVersion.ts

  if (npmDistTag) {
    return fetch(registryUrl)
      .then(res => res.json())
      .then(body => body['dist-tags'][npmDistTag])
-      .catch(() => {
+      .catch(err => {
        // eslint-disable-next-line no-console
-        console.error('error fetching version from npm registry');
+        console.error('error fetching version from npm registry:', err.message);
        return pkg.version;
      });


I also added some test coverage for this in __tests__/lib/getPkgVersion.test.ts.

kanadgupta · 2022-11-29T17:33:58Z

bin/set-major-version-tag.js

+  const parsedVersion = semverParse(pkg.version);
+
+  if (parsedVersion.prerelease.length) {
+    // eslint-disable-next-line no-console
+    console.warn('Pre-release version, not setting major version tag');
+    return;
+  }


We could use our getPkgVersion and getMajorPkgVersion functions here, but I wanted to keep this fairly vanilla so we can refer to it for a hypothetical future blog post. Plus we need some semver logic here that is pretty specific.

__tests__/cmds/docs/__snapshots__/index.test.ts.snap

src/lib/getPkgVersion.ts

kanadgupta added 20 commits November 28, 2022 17:54

refactor: rename files

0eb6fab

This consolidates getNodeVersion into another file and renames the set-version-output function to have a .js extension so we don't need to have weird `npm run lint` carveouts for it

test: more test coverage

f89ac39

refactor: use core function for output setting

91b216e

This pattern for setting outputs is now deprecated

fix: whoops

580b4f1

refactor: use semver to parse out major version

d8351d0

we were previously using a zero-deps approach but now that we need to install deps for the set-version-output step, we might as well use a safer approach here.

refactor: add ability to grab major version + test

0fc0fe2

this will set up some upcoming tagging changes

feat: create file for tagging version

90a3cf0

Merge branch 'main' into feat/major-version-tag

1936e64

docs: small update

a68b40a

Revert "refactor: add ability to grab major version + test"

a1a963a

This reverts commit 0fc0fe2.

revert(kinda): use semver major instead

5577ced

chore: do a clean install + build before version bump

c15272e

docs: update github docs URLs

674d041

docs: update MAINTAINERS guide

482cb96

i feel like this flow is better, tagging a beta tripped me up the first time

feat: surface major version tag in GHA onboarding

a3c64e2

we should surface the v8 tag in the github actions that we create. this required a decent refactor to consolidate our major version retrieval logic. a bunch of snapshots had to be updated too.

feat: surface major version tag in our docs

ec462ad

chore: small JSDoc update

341e20b

fix: don't add major tag if prerelease

5decfcc

fix: cmon dude

e7d02ff

kanadgupta commented Nov 29, 2022

View reviewed changes

kanadgupta added enhancement New feature or request refactor Issues about tackling technical debt labels Nov 29, 2022

kanadgupta marked this pull request as ready for review November 29, 2022 17:34

kanadgupta requested review from erunion and darrenyong November 29, 2022 17:34

erunion approved these changes Nov 29, 2022

View reviewed changes

__tests__/cmds/docs/__snapshots__/index.test.ts.snap Show resolved Hide resolved

src/lib/getPkgVersion.ts Outdated Show resolved Hide resolved

refactor: use logger

1b6b85d

kanadgupta merged commit dc103c0 into main Nov 29, 2022

kanadgupta deleted the feat/major-version-tag branch November 29, 2022 20:08

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: major version tags #682

feat: major version tags #682

kanadgupta commented Nov 29, 2022 •

edited

Loading

kanadgupta Nov 29, 2022

kanadgupta Nov 29, 2022

kanadgupta Nov 29, 2022

kanadgupta Nov 29, 2022

kanadgupta Nov 29, 2022

kanadgupta Nov 29, 2022

		core.setOutput('RDME_VERSION', `v${await getMajorPkgVersion('latest')}`);
		core.setOutput('NODE_VERSION', getNodeVersion());

feat: major version tags #682

feat: major version tags #682

Conversation

kanadgupta commented Nov 29, 2022 • edited Loading

🧰 Changes

🧬 QA & Testing

kanadgupta Nov 29, 2022

Choose a reason for hiding this comment

kanadgupta Nov 29, 2022

Choose a reason for hiding this comment

kanadgupta Nov 29, 2022

Choose a reason for hiding this comment

kanadgupta Nov 29, 2022

Choose a reason for hiding this comment

Footnotes

kanadgupta Nov 29, 2022

Choose a reason for hiding this comment

kanadgupta Nov 29, 2022

Choose a reason for hiding this comment

kanadgupta commented Nov 29, 2022 •

edited

Loading