PT-3107: improve release workflow (update from templates)

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @tjcouch-sil @lyonsil

.github/actions/bump-versions-action/action.yml

@@ -0,0 +1,19 @@
+name: Bump Versions Action
+description: |
+  Runs bump-versions.ts script
+
+inputs:
+  newVersion:
+    description: "Version to bump all the repo's versions to on a new branch (called `bump-versions-<version>`), e.g. 0.3.0-alpha.0."
+    required: true
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Bump repo versions
+      # Bump versions using the built-in git token https://github.com/actions/checkout/tree/v4/?tab=readme-ov-file#push-a-commit-using-the-built-in-token
+      shell: bash
+      run: |
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        npm run bump-versions -- ${{ inputs.newVersion }}

.github/workflows/bump-versions.yml

@@ -0,0 +1,51 @@
+name: Bump Versions
+run-name: Bump versions on ${{ github.head_ref || github.ref_name }} to ${{ github.event.inputs.newVersion }}
+
+on:
+  workflow_dispatch:
+    inputs:
+      newVersion:
+        description: "Version to bump all the repo's versions to on a new branch (called `bump-versions-<version>`), e.g. 0.3.0-alpha.0."
+        required: true
+
+jobs:
+  bump-versions:
+    name: Bump versions on ${{ matrix.os }}
+
+    runs-on: ${{ matrix.os }}
+
+    permissions:
+      contents: write
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+
+    steps:
+      - name: Output Workflow Dispatch Inputs
+        run: echo "${{ toJSON(github.event.inputs) }}"
+
+      - name: Checkout git repo
+        uses: actions/checkout@v4
+
+      - name: Read package.json
+        id: package_json
+        uses: zoexx/[email protected]
+        with:
+          file_path: 'package.json'
+
+      - name: Install Node and NPM
+        uses: actions/setup-node@v4
+        with:
+          cache: npm
+          node-version: ${{ fromJson(steps.package_json.outputs.volta).node }}
+
+      - name: Install packages
+        run: |
+          npm ci
+
+      - name: Bump repo versions
+        if: ${{ inputs.newVersion != '' }}
+        uses: ./.github/actions/bump-versions-action
+        with:
+          newVersion: ${{ inputs.newVersion }}

.github/workflows/publish.yml

@@ -102,7 +102,10 @@ jobs:
           omitPrereleaseDuringUpdate: true
           # make the new release a pre-release
           prerelease: true
+          # tag+commit creates a version tag for this release with the tag name at the commit ref
+          # so the GitHub Release doesn't have to create the tag and assume it is on `main`
           tag: v${{ inputs.version }}
+          commit: ${{ github.head_ref || github.ref_name }}
           # only update if the release is still a draft
           updateOnlyUnreleased: true
 
@@ -116,11 +119,9 @@ jobs:
 
       - name: Bump repo versions
         if: ${{ inputs.newVersionAfterPublishing != '' }}
-        # Bump versions using the built-in git token https://github.com/actions/checkout/tree/v4/?tab=readme-ov-file#push-a-commit-using-the-built-in-token
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          npm run bump-versions -- ${{ inputs.newVersionAfterPublishing }}
+        uses: ./.github/actions/bump-versions-action
+        with:
+          newVersion: ${{ inputs.newVersionAfterPublishing }}
 
       # Enable tmate debugging of manually-triggered workflows if the input option was provided
       - name: Setup tmate session

README.md

@@ -1,3 +1,5 @@
+<!-- Attention template README maintainers: The content in the portion of this README following the Template Info section roughly parallels that of the paranext-extension-template. When editing one, please consider whether similar changes should also be made in the other.-->
+
 # scripture-forge-platform-extensions
 
 Scripture Forge extensions for Platform.Bible
@@ -6,9 +8,11 @@ Scripture Forge extensions for Platform.Bible
 
 ## Template Info
 
-This Webpack project template is pre-configured to build an arbitrary number of Platform.Bible extensions. It contains only the essential components needed for a multi-extension repository. Note that many of the files mentioned in [Summary](#summary) are not present in this template because they describe extension code which must be added to this template. For inspiration on what extensions in a multi-extension repo could look like, refer to any repo forked from this template. A good example is [platform-bible-sample-extensions](https://github.com/paranext/platform-bible-sample-extensions).
+This is a Webpack project template pre-configured to build an arbitrary number of Platform.Bible extensions. It includes only the bare essentials required for a multi-extension repository to work.
+
+Note that many of the files mentioned in [Summary](#summary) are not present in this template because they describe extension code which must be added to this template. For examples of what extensions in a multi-extension repo might look like, refer to any repo based on this template — for instance, the [platform-bible-sample-extensions](https://github.com/paranext/platform-bible-sample-extensions).
 
-There is also a simple [template pre-configured to build a single Platform.Bible extension](https://github.com/paranext/paranext-extension-template).
+**Important:** Before proceding to use this template, consider whether you intend to build a single extension to be packaged and installed independently, or a set of related extensions that should be used together. If the former, it would be better to use the simple [template pre-configured to build a single Platform.Bible extension](https://github.com/paranext/paranext-extension-template).
 
 ### Customize repo details
 
@@ -79,6 +83,8 @@ This is a Webpack project configured to build Platform.Bible extensions. The gen
 - `dist/` is a generated folder containing the built extension files
 - `release/` is a generated folder containing zips of the built extension files
 
+> See the [Extension Anatomy wiki page](https://github.com/paranext/paranext-extension-template/wiki/Extension-Anatomy) for more information about the various files that comprise extensions and their relationships to each other.
+
 ## To install
 
 ### Install dependencies
@@ -148,14 +154,14 @@ These steps will walk you through releasing a version on GitHub and bumping the
 
 2. Manually dispatch the Publish workflow in GitHub Actions targeting the branch you want to release from (in the previous example, this would be `my-branch`). This workflow creates a new pre-release for the version you intend to release and creates a new `bump-versions-<next_version>` branch to bump the version after the release so future changes apply to a new in-progress version instead of to the already released version. This workflow has the following inputs:
 
-   - `version`: enter the version you intend to publish (e.g. 0.2.0). This is simply for verification to make sure you release the code that you intend to release. It is compared to the version in the code, and the workflow will fail if they do not match.
-   - `newVersionAfterPublishing`: enter the version you want to bump to after releasing (e.g. 0.3.0-alpha.0). Future changes will apply to this new version instead of to the version that was already released. Leave blank if you don't want to bump
-   - `bumpRef`: enter the Git ref you want to create the bump versions branch from, e.g. `main`. Leave blank if you want to use the branch selected for the workflow run. For example, if you release from a stable branch named `release-prep`, you may want to bump the version on `main` so future development work happens on the new version, then you can rebase `release-prep` onto `main` when you are ready to start preparing the next stable release.
+   - `version`: Enter the version you intend to publish (e.g. 0.2.0). This is simply for verification to make sure you release the code that you intend to release. It is compared to the version in the code, and the workflow will fail if they do not match.
+   - `newVersionAfterPublishing`: Enter the version you want to bump to after releasing (e.g. 0.3.0-alpha.0). Future changes will apply to this new version instead of to the version that was already released. Leave blank if you don't want to bump.
+   - `bumpRef`: Enter the Git ref you want to create the bump versions branch from, e.g. `main`. Leave blank if you want to use the branch selected for the workflow run. For example, if you release from a stable branch named `release-prep`, you may want to bump the version on `main` so future development work happens on the new version, then you can rebase `release-prep` onto `main` when you are ready to start preparing the next stable release.
 
     <details>
         <summary>[Optional] Create a new pre-release and bump versions branch manually </summary>
 
-   ### Manually create a new pre-release and bump versions branch
+   #### Manually create a new pre-release and bump versions branch
 
    Alternatively, you can create a new pre-release manually:
 
@@ -197,7 +203,7 @@ Following are some problems you may encounter while publishing and steps to solv
 
 If you see the following error in the GitHub Actions workflow logs while packaging:
 
-```bash
+```
 Module build failed (from ./node_modules/swc-loader/src/index.js):
 Error: Failed to load native binding
 ```
@@ -281,6 +287,8 @@ npm run update-from-templates
 
 If you encounter errors from merge conflicts, please resolve the merge conflicts, finish the commit, and run the script above again.
 
+For more information, read [the instructions on the Paranext Extension Template wiki](https://github.com/paranext/paranext-extension-template/wiki/Merging-Template-Changes-into-Your-Extension).
+
 **Note:** The merge/squash commits created when updating this repo and its extensions from the templates are important; Git uses them to compare the files for future updates. If you edit this repo's Git history, please preserve these commits (do not squash them, for example) to avoid duplicated merge conflicts in the future.
 
 <details>
@@ -341,7 +349,7 @@ Adding this import to your WebView's styles enables Tailwind CSS in the WebView.
 - [Tailwind's preflight](https://tailwindcss.com/docs/preflight) is enabled by default, meaning some default HTML tag styles are significantly modified. You can [disable it](https://tailwindcss.com/docs/preflight#disabling-preflight) or [restrict its scope](https://www.npmjs.com/package/tailwindcss-scoped-preflight) if desired. However, the preferred approach is generally to use [`@tailwindcss/typography`](https://github.com/tailwindlabs/tailwindcss-typography), included in this project's Tailwind configuration by default, when displaying flowing content.
 - You can apply theme colors using Tailwind classes corresponding to the CSS property and theme color variable name like `tw-bg-primary`.
 
-Please see the wiki's [Tailwind CSS in Web Views](https://github.com/paranext/paranext-extension-template/wiki/Extension-Anatomy#web-view-component) page for more information about using Tailwind in your web view.
+Please see the wiki's [Tailwind CSS in WebViews](https://github.com/paranext/paranext-extension-template/wiki/Extension-Anatomy#webview-component) page for more information about using Tailwind in your WebView.
 
 ### Special imports
 

lib/bump-versions.ts

@@ -3,7 +3,7 @@ import path from 'path';
 import { getExtensions } from '../webpack/webpack.util';
 import { checkForWorkingChanges, execCommand } from './git.util';
 
-// #region shared with https://github.com/paranext/paranext-extension-template/blob/main/lib/bump-versions.ts and https://github.com/paranext/paranext/blob/main/lib/bump-versions.ts
+// #region shared with https://github.com/paranext/paranext-extension-template/blob/main/lib/bump-versions.ts
 
 // This script checks out a new branch, bumps the versions of all extensions in the repo,
 // and then commits the changes. It is generally expected that you will be on `main` when you run
@@ -16,9 +16,13 @@ import { checkForWorkingChanges, execCommand } from './git.util';
 const newVersion = process.argv[2];
 const shouldAllowWorkingChanges = process.argv.includes('--allow-working-changes');
 
+// #endregion
+
+// #region shared with https://github.com/paranext/paranext-extension-template/blob/main/lib/bump-versions.ts and https://github.com/paranext/paranext/blob/main/lib/bump-versions.ts
+
 (async () => {
   // Make sure there are not working changes so we don't interfere with normal edits
-  if (!shouldAllowWorkingChanges && (await checkForWorkingChanges())) return 1;
+  if (!shouldAllowWorkingChanges && (await checkForWorkingChanges())) process.exit(1);
 
   const branchName = `bump-versions-${newVersion}`;
 
@@ -27,7 +31,7 @@ const shouldAllowWorkingChanges = process.argv.includes('--allow-working-changes
     await execCommand(`git checkout -b ${branchName}`);
   } catch (e) {
     console.error(`Error on git checkout: ${e}`);
-    return 1;
+    process.exit(1);
   }
 
   const bumpVersionCommand = `npm version ${newVersion} --git-tag-version false`;
@@ -37,7 +41,7 @@ const shouldAllowWorkingChanges = process.argv.includes('--allow-working-changes
     await execCommand(bumpVersionCommand);
   } catch (e) {
     console.error(`Error on bumping version: ${e}`);
-    return 1;
+    process.exit(1);
   }
 
   // #endregion
@@ -68,7 +72,7 @@ const shouldAllowWorkingChanges = process.argv.includes('--allow-working-changes
         });
       } catch (e) {
         console.error(`Error on bumping package version for extension ${ext.name}: ${e}`);
-        return 1;
+        process.exit(1);
       }
     }
 
@@ -83,32 +87,40 @@ const shouldAllowWorkingChanges = process.argv.includes('--allow-working-changes
       );
     } catch (e) {
       console.error(`Error on bumping manifest version for extension ${ext.name}: ${e}`);
-      return 1;
+      process.exit(1);
     }
   }
   /* eslint-enable no-restricted-syntax, no-await-in-loop */
 
   // #region shared with https://github.com/paranext/paranext-extension-template/blob/main/lib/bump-versions.ts and https://github.com/paranext/paranext/blob/main/lib/bump-versions.ts
 
+  // Format the changes
+  try {
+    await execCommand(`npm run format`);
+  } catch (e) {
+    console.error(`Error on formatting changes: ${e}`);
+    process.exit(1);
+  }
+
   // Commit the changes
   try {
     await execCommand(`git commit -a -m "Bump versions to ${newVersion}"`);
   } catch (e) {
     console.error(`Error on committing changes: ${e}`);
-    return 1;
+    process.exit(1);
   }
   // Publish the branch and push the changes
   try {
     await execCommand(`git push -u origin HEAD`);
   } catch (e) {
     console.error(`Error on publishing branch and pushing changes: ${e}`);
-    return 1;
+    process.exit(1);
   }
   console.log(
     `Bumped versions to ${newVersion} and pushed to branch ${branchName}. Please create a pull request to merge this branch into main.`,
   );
 
-  return 0;
+  process.exit(0);
 })();
 
 // #endregion

lib/git.util.ts

@@ -132,6 +132,8 @@ export async function checkForWorkingChanges(quiet = false) {
   return false;
 }
 
+// #endregion
+
 /**
  * Fetch latest from SINGLE_TEMPLATE_REMOTE_NAME
  *
@@ -283,7 +285,11 @@ export async function formatExtensionFolder(extensionFolderPath: string) {
 
     console.log(`Updated module declaration and references in types file`);
   } catch (error) {
-    console.error(`Could not update types file: ${error.message}`);
+    if (error instanceof Error) {
+      console.error(`Could not update types file: ${error.message}`);
+    } else {
+      console.error(`An unknown error occurred while updating types file: ${error}`);
+    }
   }
 
   // Update README.md
@@ -317,17 +323,24 @@ export async function formatExtensionFolder(extensionFolderPath: string) {
     const modifiedTitle = titleSection.map((line) =>
       line.replace(/paranext-extension-template/g, extensionName),
     );
-    const modifiedSummary = summarySection.map((line) =>
-      line.replace(/paranext-extension-template/g, extensionName),
-    );
+    const modifiedSummary = summarySection.map((line) => {
+      if (line.includes('https://github.com/paranext/paranext-extension-template/wiki'))
+        return line;
+
+      return line.replace(/paranext-extension-template/g, extensionName);
+    });
 
     // Reconstruct the README
     const finalLines = [...modifiedTitle, ...betweenTitleAndSummary, ...modifiedSummary, ...after];
 
     await fs.writeFile(readmePath, finalLines.join('\n'), 'utf8');
     console.log(`Updated README.md: modified title and summary sections only`);
   } catch (error) {
-    console.error(`Could not update README.md: ${error.message}`);
+    if (error instanceof Error) {
+      console.error(`Could not update README.md: ${error.message}`);
+    } else {
+      console.error(`An unknown error occurred while updating README.md: ${error}`);
+    }
   }
 
   // Update manifest.json
@@ -350,7 +363,11 @@ export async function formatExtensionFolder(extensionFolderPath: string) {
     await fs.writeFile(manifestPath, manifestContent, 'utf8');
     console.log(`Updated manifest.json with ${extensionName} information`);
   } catch (error) {
-    console.error(`Could not update manifest.json: ${error.message}`);
+    if (error instanceof Error) {
+      console.error(`Could not update manifest.json: ${error.message}`);
+    } else {
+      console.error(`An unknown error occurred while updating manifest.json: ${error}`);
+    }
   }
 
   // Update package.json
@@ -367,6 +384,10 @@ export async function formatExtensionFolder(extensionFolderPath: string) {
     await fs.writeFile(packagePath, packageContent, 'utf8');
     console.log(`Updated package.json with ${extensionName} information`);
   } catch (error) {
-    console.error(`Could not update package.json: ${error.message}`);
+    if (error instanceof Error) {
+      console.error(`Could not update package.json: ${error.message}`);
+    } else {
+      console.error(`An unknown error occurred while updating package.json: ${error}`);
+    }
   }
 }

src/scripture-forge/.gitattributes

@@ -0,0 +1,14 @@
+*       text    eol=lf
+*.exe   binary
+*.png   binary
+*.jpg   binary
+*.jpeg  binary
+*.ico   binary
+*.icns  binary
+*.eot   binary
+*.otf   binary
+*.ttf   binary
+*.woff  binary
+*.woff2 binary
+*.ldml  binary
+*.zip  binary

src/scripture-forge/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @tjcouch-sil @lyonsil

src/scripture-forge/.github/actions/bump-versions-action/action.yml

@@ -0,0 +1,19 @@
+name: Bump Versions Action
+description: |
+  Runs bump-versions.ts script
+
+inputs:
+  newVersion:
+    description: "Version to bump all the repo's versions to on a new branch (called `bump-versions-<version>`), e.g. 0.3.0-alpha.0."
+    required: true
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Bump repo versions
+      # Bump versions using the built-in git token https://github.com/actions/checkout/tree/v4/?tab=readme-ov-file#push-a-commit-using-the-built-in-token
+      shell: bash
+      run: |
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+        npm run bump-versions -- ${{ inputs.newVersion }}

src/scripture-forge/.github/assets/release-body.md

@@ -2,7 +2,7 @@ Includes:
 
 - Extension template
 
-Tested on Platform.Bible vY.Z.X. Expected to be compatible with at least vY.Z.x.
+Tested on Platform.Bible vX.Y.Z. Expected to be compatible with at least vX.Y.\*.
 
 Install instructions: