Merge pull request #344 from BuildingSync/docs/prerelease-notes

docs: add notes for making pre-releases

Author: macintoshpie

.github/workflows/publish.yml

@@ -1,8 +1,9 @@
 name: Publish
 
 on:
-  tags:
-    - 'v*.*.*'
+  push:
+    tags:
+      - 'v*.*.*'
 
 jobs:
   publish:

docs/release_instructions.md

@@ -7,13 +7,13 @@ Follow the steps below when releasing a new version
 * Checkout develop and pull the most recent changes
 
 * Update the Version in the header of the XSD in three places:
-    * Update in the <xs:schema ...> element.
-    * Update in the first <xs:annotation> element.
-    * Add enumeration to /version with the latest version 
+    * Update version the `/xs:schema@version`.
+    * Update version in the "schema title", at `/xs:schema/xs:annotation/xs:documentation[1]`.
+    * If creating an official release (i.e., you are NOT creating a pre-release), add the version as an enumeration to the `auc:BuildingSync` `version` attribute with the latest version. Though we historically added some pre-releases to `@version`, they should no longer be included.
 
 * Update the CHANGELOG.md to include the latest changes, and the most recent version.
 
-	* Run the change_log.rb script (e.g. ruby src/change_log.rb -t abcdefghijklmnopqrstuvwxyz -s 2019-12-21).
+	* Run the change_log.rb script (e.g., ruby src/change_log.rb -t abcdefghijklmnopqrstuvwxyz -s 2019-12-21). The date range must span from the last official release (ie don't start at a pre-release) until the current date.
 	* Copy the results of this into the CHANGELOG. Remove items that are not useful to an end user such as version bumps, formatting, etc.
 
 * Create a Pull Request into `master`
@@ -27,13 +27,13 @@ Check out master locally, pull changes, and create a tag and push it
 git checkout master && git pull
 git tag -a v<version> -m "<message>" [SHA]
 ```
-Where `v<version>` is a valid [semantic version](https://semver.org/) (e.g. `v1.2` or `v1.2-pr.1`) and `<message>` is the tagging message (e.g. "First official release"). See [Versioning](versioning.md) for more information.
+Where `v<version>` is a valid [semantic version](https://semver.org/) (e.g., `v1.2.3` or `v1.2.3-pr.1`) and `<message>` is the tagging message (e.g. "First official release"). See [Versioning](versioning.md) for more information.
 ```bash
 # push the tag
 git push origin 
 ```
 
-This should trigger a GitHub workflow for building and publishing the release. Once the release has been successfully published on GitHub, continue.
+This should trigger a GitHub workflow for building and publishing the release. If publishing a pre-release, you are done. Otherwise, once the release has been successfully published on GitHub, continue.
 
 ### Update BuildingSync Website