build: add version stamp to release output

* Adds a version stamp to the `package.json` in the release output. The version stamp consists of the current `HEAD` commit sha, and the branch name.

Closes #12407

Author: devversion

tools/gulp/tasks/publish.ts

@@ -52,8 +52,8 @@ task(':publish', async () => {
   if (!version.match(validVersionRegex)) {
     console.log(red(`Error: Cannot publish due to an invalid version name. Version "${version}" ` +
       `is not following our semver format.`));
-    console.log(yellow(`A version should follow this format: d.d.d, d.d.d-beta.x, d.d.d-alpha.x, ` +
-        `d.d.d-rc.x`));
+    console.log(yellow(`A version should follow this format: X.X.X, X.X.X-beta.X, X.X.X-alpha.X, ` +
+        `X.X.X-rc.X`));
     return;
   }
 

tools/package-tools/build-release.ts

@@ -7,6 +7,7 @@ import {copyFiles} from './copy-files';
 import {createEntryPointPackageJson} from './entry-point-package-json';
 import {inlinePackageMetadataFiles} from './metadata-inlining';
 import {createMetadataReexportFile} from './metadata-reexport';
+import {insertPackageJsonVersionStamp} from './package-version-stamp';
 import {createTypingsReexportFile} from './typings-reexport';
 import {replaceVersionPlaceholders} from './version-placeholders';
 
@@ -48,6 +49,8 @@ export function composeRelease(buildPackage: BuildPackage) {
   copyFiles(sourceDir, 'package.json', releasePath);
 
   replaceVersionPlaceholders(releasePath);
+  insertPackageJsonVersionStamp(join(releasePath, 'package.json'));
+
   createTypingsReexportFile(releasePath, './typings/index', name);
   createMetadataReexportFile(releasePath, './typings/index', name, importAsName);
 

tools/package-tools/package-version-stamp.ts

@@ -0,0 +1,30 @@
+import {writeFileSync} from 'fs';
+import {spawnSync} from 'child_process';
+import {buildConfig} from './build-config';
+
+/**
+ * Inserts the a version stamp, which consists of the current commit SHA and the current
+ * branch name, into the specified package.json file.
+ *
+ * This makes it easy to quickly verify the exact snapshot from which the release originated.
+ */
+export function insertPackageJsonVersionStamp(packageJsonPath: string) {
+  const packageJson = require(packageJsonPath);
+
+  packageJson['_gitCommitStamp'] = getCurrentCommitSha();
+  packageJson['_gitBranchStamp'] = getCurrentBranchName();
+
+  writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2));
+}
+
+/** Returns the commit SHA for the current git HEAD of the project. */
+function getCurrentCommitSha(): string {
+  return spawnSync('git', ['rev-parse', 'HEAD'], {cwd: buildConfig.projectDir})
+    .stdout.toString().trim();
+}
+
+/** Returns the name of the currently checked out branch of the project. */
+function getCurrentBranchName(): string {
+  return spawnSync('git', ['symbolic-ref', '--short', 'HEAD'], {cwd: buildConfig.projectDir})
+    .stdout.toString().trim();
+}