WIP: Fixups for !51

docs/CONTRIBUTING.md

@@ -22,14 +22,17 @@ of the `ITKRemoteModuleBuildTestPackageAction` repository.
 
 In order to contribute to `ITKRemoteModuleBuildTestPackageAction` you
 must have the following:
+- A computer;
+- An internet connection;
 - A [GitHub](https://github.com/) account;
-- A PC with a [git](https://git-scm.com/) client and a text editor of your choice.
+- A [git](https://git-scm.com/) client;
+- A text editor of your choice.
 
 The following are also helpful, but not strictly required:
-- A PC running the operating system for which your changes are targeted,
-  i.e. Windows, Ubuntu (Linux), or MacOS. This will allow you to test changes locally
+- A computer running the operating system for which your changes are targeted,
+  i.e. Windows, Ubuntu (Linux), or macOS. This will allow you to test changes locally
   before pushing to GitHub.
-- A Python interpreter of 3.7 or greater for testing wheels locally.
+- A Python interpreter of 3.8 or greater for testing wheels locally.
 
 Before getting started it's helpful to have a working understanding of the following:
 - ITK external modules
@@ -64,44 +67,44 @@ the fork to your local machine.
 
 ### Creating a Workflow
 
-`ITKRemoteModuleBuildTestPackageAction` is a central repository for Github Actions
+`ITKRemoteModuleBuildTestPackageAction` is a central repository for GitHub Actions
 reusable workflows for ITK external modules. Before creating a workflow, ask yourself
 the following questions:
 1. Does my workflow address a problem for ITK external modules that is not
    already solved?
-2. Does my workflow provide functionality that will generalize to various ITK external modules?
-3. Does my workflow provide functionality related to continuous integration such as
+1. Does my workflow provide functionality that will generalize to various ITK external modules?
+1. Does my workflow provide functionality related to continuous integration such as
    building, packaging, and/or testing steps?
 
 If the answer to all of the above is "yes", then continue on with your new workflow!
 
 Reference
-[Github Actions Reusable Workflow documentation](https://docs.github.com/en/actions/using-workflows/reusing-workflows#creating-a-reusable-workflow)
+[GitHub Actions Reusable Workflow documentation](https://docs.github.com/en/actions/using-workflows/reusing-workflows#creating-a-reusable-workflow)
 to get started. You will need to:
 1. Create a workflow in the `.github/workflows` folder;
-2. Define workflow inputs;
-3. Define how jobs will be launched;
-4. Define steps that a given job will take.
+1. Define workflow inputs;
+1. Define how jobs will be launched;
+1. Define steps that a given job will take.
 
 ### Modifying a Workflow
 
 Workflows will need to be maintained and updated over time as tools
 and technology progress. The best approach to modifying a workflow
 is to try to recreate steps on your local system (if possible),
-identify failures and fixes, then translate fixes to the resuable
+identify failures and fixes, then translate fixes to the reusable
 workflow in question. If you encounter an issue that requires
 community input you can ask for help on the
 [ITK community Discourse forum](https://discourse.itk.org/).
 
 ## Testing Your Changes
 
 Reusable workflows are intended to _manage continuous integration_ for
-ITK external modules in a reusable manner. At the time of writing
+ITK external modules in a reusable manner. As of January 2023
 there are unfortunately no good options for establishing continuous
-integration around proposed changes to reusable workflows themselves,
-therefore it is necessary to place an extra burden on the contributors and
-maintainers of `ITKRemoteModuleBuildTestPackageAction` to schedule tests themselves.
-Fortunately, this translates to severely reduced overhead required of the
+integration around proposed changes to reusable workflows themselves.
+It is therefore necessary to place an extra burden on the contributors
+to `ITKRemoteModuleBuildTestPackageAction` to schedule tests themselves.
+Fortunately, this severely reduces the overhead required of the
 general ITK community in maintaining continuous integration on individual
 external modules.
 
@@ -110,31 +113,34 @@ ITK external modules in a user fork. The ideal repositories to use
 for testing will depend on the workflow changes under test.
 
 The [ITKSplitComponents repository](https://github.com/InsightSoftwareConsortium/ITKSplitComponents)
-is a good target for testing relatively
-simple changes. ITKSplitComponents is a small header-only external module
-with a minimum testing suite, Python wrappings, and an example Jupyter Notebook.
-Do the following to test against ITKSplitComponents or another ITK external module:
+is a good target for testing relatively simple changes. `ITKSplitComponents`
+is a small header-only external module with a minimum testing suite,
+Python wrappings, and an example Jupyter Notebook.
+Do the following to test against `ITKSplitComponents` or another ITK external module:
 1. Commit your changes to `ITKRemoteModuleBuildTestPackageAction` and
-   push to make them available on your GitHub user account:
+   push to make them available on your GitHub user account. See the
+   [ITK "Contributing" documentation](https://github.com/InsightSoftwareConsortium/ITK/blob/master/CONTRIBUTING.md#commit-messages)
+   for guidelines on writing commit messages in the ITK ecosystem.
 ```sh
-> git commit
-> git push
+$ git commit
+$ git push
 ```
 
-2. Fork the [ITKSplitComponents repository](https://github.com/InsightSoftwareConsortium/ITKSplitComponents)
+1. Fork the [ITKSplitComponents repository](https://github.com/InsightSoftwareConsortium/ITKSplitComponents)
     to your GitHub user account and clone to your local machine:
 ```sh
-> cd ..
-> git clone [email protected]:<your-username>/ITKSplitComponents.git
-> cd ITKSplitComponents
+$ cd ..
+$ git clone [email protected]:<your-username>/ITKSplitComponents.git
+$ cd ITKSplitComponents
 ```
 
-3. Create a development branch for your proposed changes:
+1. Create a development branch for your proposed changes:
 ```sh
-> git checkout -b "my-cool-feature"
+$ git checkout -b "my-cool-feature"
 ```
 
-4. Update the external module workflow `.yml` file to reference your changes:
+1. Update the external module workflow `.yml` file to reference your changes. Either the name of the
+development branch or the desired development commit hash may be used to reference workflows.
 ```yml
 name: Build, test, package
 
@@ -152,13 +158,13 @@ jobs:
       pypi_password: ${{ secrets.pypi_password }}
 ```
 
-5. Commit and push your changes:
+1. Commit and push your changes:
 ```sh
-> git commit
-> git push
+$ git commit
+$ git push
 ```
 
-6. Visit `https://github.com/<your-username>/ITKSplitComponents/actions` to view running GHA jobs.
+1. Visit `https://github.com/<your-username>/ITKSplitComponents/actions` to view running Github Actions jobs.
 
 Other ITK external modules may also be used for testing:
 - [ITKBSplineGradient](https://github.com/insightSoftwareConsortium/ITKbsplinegradient) can be
@@ -175,9 +181,9 @@ creating a
 1. Visit `https://github.com/<your-username>/ITKRemoteModuleBuildTestPackageAction/pulls` and
    click the green "New Pull Request" button to create a pull request for merging changes
    from your development branch into `InsightSoftwareConsortium/main`.
-2. Describe your changes and create the pull request.
+1. Describe your changes and create the pull request.
 
-Each nontrivial `ITKRemoteModuleBuildTestPackageAction` pull request *must* include a
+Each nontrivial `ITKRemoteModuleBuildTestPackageAction` pull request _must_ include a
 link to a successful GitHub Actions test run in its description. Refer to the
 [Testing Your Changes](#testing-your-changes) section for instructions on how to
 set up a test run in a user fork of an ITK external module.