Better update instructions (#228)

Author: MikaelMayer

CONTRIBUTING.md

@@ -1,14 +1,27 @@
 # Release process:
 
+## Semi-automated release process (preferred)
+
+1. Run `./publish_process.js` (with Node installed)
+   - Choose to bump the patch, minor or major version as asked.
+   - Fix the ChangeLog that is automatically populated and opened for you.
+   - If there is a new release of Dafny, it will suggest to bump the Dafny version.
+   Then it creates the branch, pushes it and give you a link for the PR.
+2. Create the PR, have it reviewed and merged (adding more commits is fine)
+3. Relaunch the script. It will detect the PR merge;
+   - Confirm the publication of the new version.
+
+## Manual release process stps
+
 1. Look for all the recent changes since the last version https://github.com/dafny-lang/ide-vscode/commits/master
    and write a summary of each relevant commit in `CHANGELOG.md`
 2. Update `package.json`
   - Upgrade the version number of the extension in `package.json` (line 5) (let's assume it's A.B.C)
   - [If Dafny changed] Search for `"dafny.preferredVersion":`, and add the most recent Dafny version number to the head of the list (let's assume it's X.Y.Z)
 3. [If Dafny changed] Update `src/constants.ts`
   - Change `LanguageServerConstants.LatestVersion = "X.Y.Z"` for the same version number that you put.
-4. Commit your changes in a branch named `dafny-X.Y.Z` (if Dafny changed) or `tag-A.B.C` (if only the VSCode extension changed)
-   Your commit message could be `chore: Bump version to A.B.C`
+4. Commit your changes in a branch named `release-A.B.C
+   Your commit message could be `chore: Release vA.B.C` optionally adding ` with support for Dafny X.Y.Z`
 5. Push this branch on the server, have it merged (after necessary approval)
 6. Pull the most recent master branch of the extension.
 7. Add the tag with the command `git tag vA.B.C` and push it with `git push origin vA.B.C`

package.json

@@ -203,7 +203,6 @@
           "enum": [
             "latest",
             "3.7.3",
-            "3.7.2",
             "3.6.0",
             "3.5.0",
             "3.4.2",

publish_process.js

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+
+/**
+Perform the next step to publish the extension.
+ i. Verifies that it's on the master branch. If not so, terminate. Otherwise, pulls the latest master version.
+ii. If the last message on master indicates Version X.Y.Z and it does not have a tag.
+    it means that steps iii. to vii. were executed correctly.
+    Ask whether it's ready to publish (ENTER or y)
+    - if so, create and publish the tag
+    - Otherwise, cancel.
+
+iii. Fetches all tags, and verify that there is no version tag.
+ iv. Asks to bump the patch version (ENTER or p), the minor version (m) or the major version (M)
+  v. Populates the CHANGELOG.md with the most recent commit messages.
+ vi. If a newest version of Dafny is found, ask whether to refer to it as the latest (ENTER or y), or no (n)
+vii. Follows the steps of CONTRIBUTING.
+     Ask to revise the CHANGELOG.md as needed
+     (n or anything else) : Abruptly stop.
+     (ENTER or y) : Creates a branch named "version-X.Y.Z"
+                    Commits the files to this branch with message "Version X.Y.Z"
+                    Push the branch.
+     Indicate that the PR should be merge without changing the commit message.
+     Indicate that the script just needs to be relaunched once the PR is approved and merged.
+*/
+
+const fs = require("fs");
+const { promisify, getSystemErrorMap } = require('util');
+const exec = require('child_process').exec;
+const execAsync = promisify(exec);
+const readline = require('readline');
+const fetch = (url, init) =>
+  import('node-fetch').then(({ default: fetch }) => fetch(url, init));
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+const question = function(input) {
+  return new Promise((resolve, reject) => {
+    rl.question(input, resolve);
+  });
+}
+const changeLogFile = "CHANGELOG.md";
+const dafnyReleasesURL = 'https://api.github.com/repos/dafny-lang/dafny/releases';
+const constantsFile = "src/constants.ts";
+const packageFile = "package.json";
+const packageLockFile = "package-lock.json";
+const ABORTED = "ABORTED";
+const ACCEPT_HINT = "(ENTER)";
+
+function ok(answer) {
+  return answer.toLowerCase() == "y" || answer == "";
+}
+
+async function getCurrentBranch() {
+  return (await execAsync("git branch --show-current")).stdout.trim();
+}
+
+// Ensures that the working directory is clean
+async function ensureWorkingDirectoryClean() {
+  var unstagedChanges = (await execAsync("git diff")).stdout.trim() + (await execAsync("git diff --cached")).stdout.trim();
+  if(unstagedChanges != "") {
+    console.log("Please commit your changes before launching this script.");
+    throw ABORTED;
+  }
+}
+
+async function ensureMaster() {
+  await ensureWorkingDirectoryClean();
+  var currentBranch = getCurrentBranch();
+  if(currentBranch != "master") {
+    console.log(`You need to be on the 'master' branch to release a new version.`);
+    if(!ok(await question(`Switch from '${currentBranch}' to 'master'? ${ACCEPT_HINT}`))) {
+      console.log("Publishing script aborted.");
+      throw ABORTED;
+    }
+    console.log("switched to master branch");
+    console.log((await execAsync("git checkout master")).stdout);
+    currentBranch = getCurrentBranch();
+    if(currentBranch != "master") {
+      console.log("Failed to checkout master");
+      throw ABORTED;
+    }
+  }
+  await execAsync("git pull");
+  console.log("Latest master checked out")
+}
+
+async function isTagMissing() {
+  var tagList = (await execAsync("git show-ref --tags")).stdout.trim();
+  // recovers the last commit hash
+  var lastCommitHash = (await execAsync("git log -1 --pretty=%H")).stdout.trim();
+  // checks if the last commit hash is in the tag list:
+  var tagListRegex = new RegExp(`^${lastCommitHash}\\s*refs/tags/(\\w*)`);
+  var match = tagListRegex.exec(tagList);
+  if(match == null) {
+    return true;
+  }
+  console.log(`The current master already has the tag ${match[1]}. Nothing needs to be done.\nIf you want to push the tag again, run 'git push --tags'`);
+  throw ABORTED;
+}
+
+async function changeLogAndVersion() {
+  let changeLog = await fs.promises.readFile(changeLogFile, "utf8");
+  const currentDocumentVersionRegex = /^#\s*Release Notes\s*##\s*(\d+.\d+.\d+)/;
+  const match = currentDocumentVersionRegex.exec(changeLog);
+  if(match == null) {
+    console.log(`Could not find ${currentDocumentVersionRegex} in ${changeLogFile}`);
+    throw ABORTED;
+  }
+  const currentChangeLogVersion = match[1];
+  const updateChangeLogWith = ((changeLog, oldVersion) => async function(newVersion, messages) {
+    const newChangeLog = changeLog.replace(currentDocumentVersionRegex, match => 
+      `# Release Notes\n\n## ${newVersion}\n${messages}\n\n## ${oldVersion}`);
+    await fs.promises.writeFile(changeLogFile, newChangeLog);
+    return true;
+  })(changeLog, currentChangeLogVersion);
+  return {updateChangeLogWith, currentChangeLogVersion};
+}
+
+async function getMostRecentDafnyRelease() {
+  let mostRecentDafnyRelease = null;
+  const dafnyReleases = await (await fetch(dafnyReleasesURL)).json();
+  for(var i = 0; i < dafnyReleases.length && mostRecentDafnyRelease == null; i++) {
+    if(dafnyReleases[i].tag_name != "nightly") {
+      mostRecentDafnyRelease = dafnyReleases[i].tag_name;
+      break;
+    }
+  }
+  if(mostRecentDafnyRelease == null) {
+    console.log(`Could not fetch the latest Dafny release version from ${dafnyReleasesURL}`);
+    throw ABORTED;
+  }
+  return mostRecentDafnyRelease;
+}
+
+
+async function readPackageJson() {
+  const packageContent = await fs.promises.readFile(packageFile);
+  const packageObj = JSON.parse(packageContent);
+  return packageObj;
+}
+
+async function writePackage(packageObj) {
+  await fs.promises.writeFile(packageFile, JSON.stringify(packageObj, null, 2));
+}
+
+// returns the new version number
+async function nextVersion(currentVersion) {
+  const currentVersionRegex = /(\d+)\.(\d+)\.(\d+)/;
+  const match = currentVersionRegex.exec(currentVersion);
+  if(match == null) {
+    console.log(`Could not parse version ${currentVersion}`);
+    throw ABORTED;
+  }
+  var bumpedPatch = `${match[1]}.${match[2]}.${parseInt(match[3]) + 1}`;
+  var bumpedMinor = `${match[1]}.${parseInt(match[2]) + 1}.0`;
+  var bumpedMajor = `${parseInt(match[1]) + 1}.0.0`;
+  console.log("Should the next version be:");
+  console.log(`${currentVersion} => ${bumpedPatch}? ${ACCEPT_HINT}`);
+  console.log(`${currentVersion} => ${bumpedMinor}? (m)`);
+  var answer = await question(`${currentVersion} => ${bumpedMajor}? (M)\n`);
+  if(ok(answer)) {
+    return bumpedPatch;
+  } else if(answer == "m") {
+    return bumpedMinor;
+  } else if(answer == "M") {
+    return bumpedMajor;
+  } else {
+    console.log("Publishing script aborted.");
+    throw ABORTED;
+  }
+}
+
+async function getLastPreparedTag() {
+  const lastCommitMessage = (await execAsync("git log -1 --pretty=%B")).stdout.trim();
+  const lastCommitMessageRegex = /(v\d+\.\d+\.\d+)/;
+  const match = lastCommitMessageRegex.exec(lastCommitMessage);
+  if(match == null) {
+    return false;
+  }
+  return match[1];
+}
+
+function getCommandLine() {
+  switch (process.platform) { 
+     case 'darwin' : return 'open';
+     case 'win32' : return 'start';
+     case 'win64' : return 'start';
+     default : return 'xdg-open';
+  }
+}
+
+async function getAllRecentCommitMessagesFormatted(currentChangeLogVersion) {
+  // Query git for all the commit messages from currentChangeLogVersion (excluded) to the latest commit (included)
+  var raw = (await execAsync(`git log --pretty=%B v${currentChangeLogVersion}..HEAD`)).stdout.trim();
+  raw = "- " + raw.trim().replace(/\n\s*/g, "\n- ");
+  raw = raw.replace(/\(#(\d+)\)/g, "(https://github.com/dafny-lang/ide-vscode/pull/$1)");
+  raw = raw.trim();
+  raw = raw.replace(/\n.*$/, ""); // Removes the last one, because it's the last release commit.
+  return raw.trim();
+}
+
+function close() {
+  rl.close();
+  return false;
+}
+
+async function updatePackageJson(packageObj, newVersion, mostRecentDafnyRelease) {
+  packageObj["version"] = newVersion;
+  var versionList = packageObj["contributes"]["configuration"]["properties"]["dafny.preferredVersion"]["enum"];
+  // versionList starts with "latest", and then the last version
+  var previousDafnyVersion = versionList[1];
+  var updatedDafny = false;
+  if (previousDafnyVersion != mostRecentDafnyRelease) {
+    if (ok(await question(`The Dafny version in the package.json file (${previousDafnyVersion}) is not the latest (${mostRecentDafnyRelease}). Do you want to update it? ${ACCEPT_HINT}`))) {
+      var previousDafnyVersionListHead = versionList[1];
+      // If the previous dafny version is just different from mostRecentDafnyRelease by the patch number, replace it, otherwise insert it using splice
+      if (previousDafnyVersionListHead == mostRecentDafnyRelease.substring(0, mostRecentDafnyRelease.lastIndexOf("."))) {
+        versionList[1] = mostRecentDafnyRelease;
+      } else {
+        versionList.splice(1, 0, mostRecentDafnyRelease);
+      }
+
+      console.log("Updated Dafny version to " + mostRecentDafnyRelease);
+      var constantsContent = await fs.promises.readAsync(constantsFile, "utf8");
+      var constantsContentRegex = /const\s*LatestVersion\s*=\s*'\d+.\d+.\d+';/;
+      constantsContent.replace(constantsContentRegex, `const LatestVersion = '${mostRecentDafnyRelease}';`);
+      await fs.promises.writeAsync(constantsFile, constantsContent);
+      updatedDafny = true;
+    } else {
+      console.log("Ignoring new Dafny version.");
+    }
+  }
+  await writePackage(packageObj);
+  return updatedDafny;
+}
+
+async function UpdateChangeLog(currentChangeLogVersion, packageObj, updateChangeLogWith, newVersion) {
+  var allRecentCommitMessages = await getAllRecentCommitMessagesFormatted(currentChangeLogVersion);
+  if (packageObj["version"] == currentChangeLogVersion) {
+    await updateChangeLogWith(newVersion, allRecentCommitMessages);
+    console.log("I changed " + changeLogFile + " to reflect the new version.\nPlease make edits as needed and close the editing window.");
+    await execAsync(getCommandLine() + ' ' + changeLogFile);
+    if (!await question(`Ready to continue? ${ACCEPT_HINT}`)) {
+      console.log("Aborting.");
+      throw ABORTED;
+    }
+    currentChangeLogVersionCheck = (await changeLogAndVersion()).currentChangeLogVersion;
+    if (currentChangeLogVersionCheck != newVersion) {
+      console.log(`The last version was supposed to be ${newVersion}, but the changelog was updated to ${currentChangeLogVersionCheck}. Aborting publishing.`);
+      throw ABORTED;
+    }
+  } else {
+    console.log("ChangeLog.md already up-to-date");
+  }
+  return answer;
+}
+
+async function HandleFinalPublishingProcess(currentChangeLogVersion, lastPreparedTag) {
+  if ("v" + currentChangeLogVersion == lastPreparedTag) {
+    // Tag the current commit
+    console.log(`The changelog already mentions version ${currentChangeLogVersion}.\nYou now need to create the tag ${lastPreparedTag} and publish it to release this new version.`);
+    // ask for confirmation, and publish the tag.
+    if (ok(await question(`Create and publish the tag ${lastPreparedTag}? ${ACCEPT_HINT}`))) {
+      console.log(`Creating tag ${lastPreparedTag}...`);
+      await execAsync(`git tag ${lastPreparedTag}`);
+      console.log(`Publishing tag ${lastPreparedTag}...`);
+      await execAsync(`git push origin ${lastPreparedTag}`);
+      console.log(`${lastPreparedTag} published. The CI will take care of releasing the new VSCode extension.`);
+    } else {
+      console.log("Just run the script again when you are ready to publish the version. Aborting.");
+      throw ABORTED;
+    }
+  } else {
+    console.log("Something went wrong. I found " + lastPreparedTag + " in the last commit message, and this tag is not published yet.");
+    console.log("However, the changelog mentions a different version:" + currentChangeLogVersion);
+    console.log("Please fix the current state");
+    throw ABORTED;
+  }
+}
+
+async function Main() {
+  try {
+    // verify that we are on the master branch.
+    await ensureMaster();
+    await isTagMissing();
+    let {updateChangeLogWith, currentChangeLogVersion} = await changeLogAndVersion();
+
+    const lastPreparedTag = await getLastPreparedTag();
+    if(lastPreparedTag) {
+      // Here we only need to publish the last prepared tag
+      await HandleFinalPublishingProcess(currentChangeLogVersion, lastPreparedTag);
+      return;
+    }
+
+    let newVersion = await nextVersion(currentChangeLogVersion);
+    let mostRecentDafnyRelease = await getMostRecentDafnyRelease().substring(1);
+    let packageObj = await readPackageJson();
+    
+    console.log(`Going to proceed to publish ${newVersion}`);
+    // Get all the commit messages since the last published tag
+    await UpdateChangeLog(currentChangeLogVersion, packageObj, updateChangeLogWith, newVersion);
+    // All clear, we can modify constants.ts and package.json.
+
+    var updatedDafny = await updatePackageJson(packageObj, newVersion, mostRecentDafnyRelease);
+    // Execute npm install to ensure the package lock is up to date
+    console.log("Executing `npm install`...");
+    await execAsync("npm install");
+
+    // Create the new branch and git add all the files modified above
+    console.log("Creating new branch...");
+    const newBranch = `release-${newVersion}`;
+    await execAsync(`git checkout -b ${newBranch}`);
+    await execAsync(`git add ${changeLogFile} ${packageFile} ${constantsFile} ${packageLockFile}`);
+    if(ok(await question(`I made all the necessary edits. Push the changes to the remote repository? ${ACCEPT_HINT}`))) {
+      await execAsync(`git commit -m "Release v${newVersion}${ updatedDafny ? ` (updated Dafny to ${mostRecentDafnyRelease})` : "" }"`);
+      await execAsync(`git push origin ${newBranch}`);
+      console.log("Now, create the pull request by clicking the link below:");
+      console.log(`https://github.com/dafny-lang/ide-vscode/compare/${newBranch}?expand=1`);
+      console.log("When this PR is approved and merged, launch this script again to finish publishing the release.");
+    } else {
+      console.log("Aborting publishing.");
+      return close();
+    }
+
+  } catch(e) {
+    if(e != ABORTED) {
+      throw e;
+    }
+  } finally {
+    close();
+  }
+}
+Main();
+