From e9e3ecfd1c57f5081966c6852273075c27af40f8 Mon Sep 17 00:00:00 2001 From: Timo Tijhof Date: Wed, 12 Jun 2024 20:56:23 +0100 Subject: [PATCH] Build: Remove pushing of release artefact to detached Git commit For QUnit 1.x and QUnit 2.x, we supported use of QUnit via Git submodules, where we put the Git tag on a commit that isn't in the main line, but instead a detached commit that contains the release artefacts. This is also what Bower built on top of. These two distribution methods will continue to work for old releases, but QUnit 3.0 will instead only be canonically published to code.jquery.com from where it can be downloaded over HTTP and HTTPS (for setups that prefer something simpler than npm). This means we don't need a separate "prepare" and "release" commit, so merge these steps into one, and place the tag on the main branch commit instead. This also means we need to do our version field differently. We can: * Keep "-pre" in Git, but have the release step temporarily remove it without including in the tagged commit. * Change proper version for the release commit, then push another commit that changes it back. * Use the proper version always, and let the build step inject "-dev" for non-release builds. I went with the third option, which seems most conventional in the JS ecosystem these days to simply leave it at the last release number between releases. Ref https://github.com/qunitjs/qunit/issues/1677. --- RELEASE.md | 71 +++++++++++++++++++++++------------------- build/build-release.js | 1 + build/dist-replace.js | 4 +-- build/prep-release.js | 4 +-- package-lock.json | 4 +-- package.json | 2 +- 6 files changed, 47 insertions(+), 39 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index cbc0bdf95..4a3b1d7b1 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -4,7 +4,6 @@ This guide walks you through the QUnit release. QUnit aims for its releases to be reproducible. Recent releases are automatically verified on a regular basis ([reproducible builds status](https://github.com/qunitjs/qunit/actions/workflows/reproducible.yaml)). Read more on [Wikipedia](https://en.wikipedia.org/wiki/Reproducible_builds), and [reproducible-builds.org](https://reproducible-builds.org/). - ⚠️ **WARNING** ⚠️ > Before starting, make sure you have: @@ -14,12 +13,14 @@ QUnit aims for its releases to be reproducible. Recent releases are automaticall > > System prerequisites: > -> * Node.js 14, or later. +> * Node.js 18, or later. > * Git 2.11, or later. Ensure that all changes for this release have been merged into the main branch. For patch releases, try landing any other bug fixes; for minor releases, ensure new features have been documented and tested. Major releases likely have their own checklist. -1. Create a local `release` branch, and ensure it is up-to-date: +## Preparing the release + +1. Create a local `release` branch, and ensure it is up-to-date: Verify that the canonical repository is cloned (not a fork): ``` git remote -v @@ -36,7 +37,7 @@ Ensure that all changes for this release have been merged into the main branch. npm ci ``` -3. Create the release preparation commit: +3. Prepare for the release commit: ``` node build/prep-release.js @VERSION ``` @@ -45,24 +46,6 @@ Ensure that all changes for this release have been merged into the main branch. * In `AUTHORS.txt`, if you see duplicate entries, then use the `.mailmap` file to normalize them to a canonical name and e-mail address, and then re-run the above command. * Edit `History.md` to remove changes not relevant to end-users (e.g. changes relating to tests, build, internal refactoring, doc fixes, etc.). - Commit your changes with the following message (replace `@VERSION` with the release version): - ``` - Build: Prepare @VERSION release - ``` - - Push the `release` branch to GitHub. - Once CI is passing, push again, this time to the (protected) `main` branch. - -## Performing the release - -Verify that your local repo is at the release preparation commit: - -``` -git show -# Build: Prepare x.y.z release -# … -``` - 4. Build the release: ``` node build/build-release.js @VERSION @@ -73,13 +56,38 @@ git show ``` node build/review-package.js @LAST_VERSION - # … reviews package.json, qunit.js, and qunit.css + # … review package.json, qunit.js, and qunit.css + ``` + + Commit your changes with the following message (replace `@VERSION` with the release version): + ``` + Release @VERSION ``` -5. Publish to GitHub.
⚠️ Do not push to the main branch! + Push the `release` branch to GitHub. + Once CI is passing, push again, this time to the (protected) `main` branch. + +## Publish the release + +Verify that your local repo is on a clean main branch checkout with HEAD at the release commit: + +``` +git show +# Release x.y.z +# … +``` + +And that you have release artefacts from the previous step in your working directory (i.e. same version, and not a "dev" version). If you don't have this, go back to step 4 "Build the release". + +``` +head qunit/qunit.js +# /*! +# * QUnit x.y.z +# … +``` + +5. Publish tag to GitHub. ``` - git add -f package.json qunit/ - git commit -m "Release @VERSION" git tag -s "@VERSION" -m "Release @VERSION" git push --tags ``` @@ -102,21 +110,20 @@ git show ## Updating the website -After the release is published, we need to update the website. - -Check out the main branch of the [qunitjs/qunit](https://github.com/qunitjs/qunit) repository, and ensure it is clean and up-to-date. Run the following script, which will update release links and demos to use the new version: +After the release is published, we need to update the website. Run the following script, which will update download links and demos to use the new version: ``` -qunit$ node build/site-set-version.js VERSION +qunit$ git remote update && git checkout -B docs -t origin/main +qunit$ node build/site-set-version.js @VERSION ``` Stage the changes it made, and commit with the following message: ``` -Docs: Update url and version to VERSION +Docs: Update url and version to @VERSION ``` -Push the commit to a branch on origin, wait CI checks to complete, then re-push to the main branch. Check the website in a few minutes to verify the change ([deployment log](https://github.com/qunitjs/qunit/deployments/activity_log?environment=github-pages)). +Push the commit to a new branch on the origin, wait for CI checks to complete, then re-push to the main branch. Check the website after a few minutes to verify the change ([deployment log](https://github.com/qunitjs/qunit/deployments/activity_log?environment=github-pages)). ## Final steps diff --git a/build/build-release.js b/build/build-release.js index 79c99b539..fe6453c0b 100644 --- a/build/build-release.js +++ b/build/build-release.js @@ -45,6 +45,7 @@ const Repo = { } { console.log('Running `npm run build`...'); + process.env.QUNIT_BUILD_RELEASE = '1'; cp.execFileSync('npm', [ 'run', 'build' diff --git a/build/dist-replace.js b/build/dist-replace.js index 250b30f4c..5d158097e 100644 --- a/build/dist-replace.js +++ b/build/dist-replace.js @@ -8,9 +8,9 @@ let distVersion = require('../package.json').version; -if (/pre/.test(distVersion)) { +if (!process.env.QUNIT_BUILD_RELEASE) { // During development, include a timestamp. - distVersion += ' ' + (new Date()).toISOString().replace(/:\d+\.\d+Z$/, 'Z'); + distVersion += '-dev ' + (new Date()).toISOString().replace(/:\d+\.\d+Z$/, 'Z'); } const replacements = { diff --git a/build/prep-release.js b/build/prep-release.js index 628ff1a55..b87cff0fa 100644 --- a/build/prep-release.js +++ b/build/prep-release.js @@ -117,7 +117,7 @@ const Repo = { const packageIndentation = json.match(/\n([\t\s]+)/)[1]; const data = JSON.parse(json); - data.version = `${version}-pre`; + data.version = version; fs.writeFileSync( filePath, @@ -132,7 +132,7 @@ const Repo = { const packageIndentation = json.match(/\n([\t\s]+)/)[1]; const data = JSON.parse(json); - data.version = data.packages[''].version = `${version}-pre`; + data.version = data.packages[''].version = version; fs.writeFileSync( filePath, diff --git a/package-lock.json b/package-lock.json index f8dea6b2f..4595919b4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "qunit", - "version": "2.21.0-pre", + "version": "2.21.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "qunit", - "version": "2.21.0-pre", + "version": "2.21.0", "license": "MIT", "dependencies": { "commander": "7.2.0", diff --git a/package.json b/package.json index fc5aba8ea..2e0b186ba 100644 --- a/package.json +++ b/package.json @@ -2,7 +2,7 @@ "name": "qunit", "title": "QUnit", "description": "The powerful, easy-to-use testing framework.", - "version": "2.21.0-pre", + "version": "2.21.0", "homepage": "https://qunitjs.com", "author": { "name": "OpenJS Foundation and other contributors",