Documentation improvements (BUNPC#88)

* Fix links to markdown files

* Update CONTRIBUTING.md

Author: sstucker

CONTRIBUTING.md renamed to .github/CONTRIBUTING.md

@@ -1,13 +1,23 @@
 # Contributing
 
-We welcome contributions to the Homer3 open-source software package from the fNIRS community! This document describes the preferred procedure for adding or editing code to the app. 
+We welcome contributions to the Homer3 open-source software package from the fNIRS community! This document describes the procedures for adding and editing code as well as building releases of the application for distribution. 
 
-It is recommended that contributors familiarize themselves with Git and GitHub before attempting to contribute to Homer3. Links to relevant documentation are included here for your convenience.
-
-For a walkthrough of the contribution procedure, see [WORKFLOW.md](WORKFLOW.md). Version control software and contribution procedures are complicated, but there is no other way to achieve collaborative development. 😊
+It is recommended that contributors familiarize themselves with Git and GitHub before attempting to contribute to Homer3. Links to relevant documentation are included here for your convenience. For a walkthrough of the contribution procedure, see [WORKFLOW.md](WORKFLOW.md). Version control software and contribution procedures are complicated, but there is no other way to achieve collaborative development. 😊
 
 > Note: As of October 2021, code shared with other applications in the openfnirs ecosystem such as the DataTree and Utils libraries are managed as submodule repositories. Submodules cannot be managed using GitHub desktop.
 
+## Release and versioning procedures
+
+[Homer3 releases](https://github.com/BUNPC/Homer3/releases) are composed of frozen source code plus compiled versions of the software for use with the [MATLAB Runtime](https://www.mathworks.com/products/compiler/matlab-runtime.html) on Windows and MacOS.
+
+Releases are to be built as often as important fixes and features are merged with the `master` branch and then tested.
+
+Each release is associated with a [version tag](https://github.com/BUNPC/Homer3/tags), i.e. [`v1.32.3`](https://github.com/BUNPC/Homer3/releases/tag/v1.32.3).
+
+As of November 2021, pull requests and commits need not increment the version tag, but version tags MUST be incremented before building a new release. The tag associated with a release CANNOT be changed unless the release is marked draft/is a pre-release.
+
+For a description of how to generate and package a release for distribution, see [RELEASE.md](RELEASE.md).
+
 ## Fork and pull model
 
 Following the [fork and pull model](https://docs.github.com/en/github/collaborating-with-pull-requests/getting-started/about-collaborative-development-models#fork-and-pull-model), contributors are expected to make their changes in their [fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of the repository and to [create pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to integrate these changes with a branch of the BUNPC repository after they are reviewed by the community.
@@ -23,13 +33,16 @@ Pull requests must meet the following requirements:
 - Commit messages or the pull request description must fully document the proposed changes
 - Relevant issues and milestones must be linked
 - Relevant submodule pull requests must be linked
+- Pull requests require review before they can be merged into `master` or `development`.
 
 ### Branches
 
-The `master` branch should contain the most stable version of the working code. Releases are stable freezes of the master branch. Changes made directly to the master branch must address an issue.
+The `master` branch should contain the most stable version of the working code. Releases are stable freezes of the master branch. Changes made directly to the master branch must address an issue or bug and be relatively small.
 
 The `development` branch integrates finished features and fixes. The development branch is synced with the master branch periodically.
 
+No one can push to master without creating a PR. **Administrators may push to `development` but are but are strongly encouraged not to.**
+
 Depending on the scale of the changes, it may be preferable to direct pull requests to a *feature branch*: this is a branch created to integrate related changes prior to merging them with the development code. This is especially useful when multiple developers are working on the same large feature, i.e. a new GUI panel being developed in `plotprobe-2`. [Creating a milestone](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) related to a feature branch can help to facilitate discussion about collaborative development.
 
 ## Submodules
@@ -50,9 +63,11 @@ An [intallation of Git](https://git-scm.com/book/en/v2/Getting-Started-Installin
 
 Homer3 is a MATLAB applicaton. In order to support users who do not have MATLAB licenses, we release a compiled build of Homer3 for use with the [MATLAB Runtime environment](https://www.mathworks.com/products/compiler/matlab-runtime.html).
 
-These builds target MATLAB R2017b (9.3). Therefore, the use of functions introduced to MATLAB after R2017b (9.3) is not supported.
+As of November 2021, these builds target MATLAB R2020b (9.9) as well as MATLAB R2017b (9.3). Therefore, the use of functions introduced to MATLAB after R2020b (9.9) is not supported.
+
+The use of 2020b is therefore recommended for development purposes.
 
-The use of 2017b is therefore recommended for development purposes.
+We compile these releases for Windows and MacOS. Linux is not supported.
 
 ## Walkthrough
 

.github/RELEASE.md

@@ -0,0 +1,37 @@
+# Homer3 Release Procedures
+
+This document describes the procedure for building and hosting a release of Homer3. A release of Homer3 consists of the source code packaged with a MATLAB Runtime executable for both Windows and MacOS.
+
+## Creating a GitHub release
+
+GitHub releases is used to host the frozen source code and [MATLAB Runtime](https://www.mathworks.com/products/compiler/matlab-runtime.html) executables. Create a new release by clicking "Draft a new release" at the top of the [Releases page](https://github.com/BUNPC/Homer3/releases). Leave the release in draft state and in pre-release state until it can be tested. See the [GitHub docs](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) for more information about managing releases.
+
+Release notes should be created from the commit messages logged since the last release was tagged.
+
+## Packaging the latest source code
+
+Create a .zip archive containing the latest source code from the master branch, making sure to include submodules. Remove all version control files from the `master` branch, including `.gitignore`. This can be accomplished with the following shell commands:
+
+```bash
+git clone https://github.com/BUNPC/Homer3 --single-branch -b master --recurse-submodules
+rm -rf .git\
+rm .gitignore
+```
+
+Rename the zip file `homer3_src_<version tag>_<platform>_<target MATLAB env>` i.e. `homer3_src_v1_26_0_win_R2017b.zip` or `homer3_src_v1_32_1_mac_R2020b.zip` and upload it to the GitHub release.
+
+> Note: as of November 2021, unfortunately the automatically generated source code does NOT contain submodules! That is why we generate this archive manually.
+
+## Creating MATLAB Runtime executables for Windows and Mac
+
+Cross-compilation is not possible with the MATLAB compiler. The following must be repeated within both a Mac and Windows environment:
+
+Linux is not supported.
+
+1. Download and install MATLAB Runtime corresponding to the MATLAB version the build targets. **As of November 2020, this is MATLAB R2017b (9.3) and R2020b.**
+2. Download the latest version of the master branch. In the MATLAB command window, navigate to the Homer3 root folder.
+3. Execute `setpaths`
+4. Execute `createInstallFile()`
+5. Zip up the resulting install files which will be generated at `Homer3\Install\homer3_install`.
+6. Rename this zip file `homer3_install_<version tag>_<platform>_<target MATLAB env>` i.e. `homer3_install_v1_26_0_win_R2017b.zip` or `homer3_install_v1_32_1_mac_R2020b.zip`.
+7. Upload the renamed archive to the GitHub release.

WORKFLOW.md renamed to .github/WORKFLOW.md

@@ -15,10 +15,10 @@ Homer3 is composed only of MATLAB scripts, so the installation process for MATLA
 
 [Getting started with Homer3](https://github.com/BUNPC/Homer3/wiki/Getting-started-with-Homer3)
 
-Note that cloning the repository or using the Download .zip button on the repository webpage will not download the submodule libraries that are a part of Homer3. Without these, the application will not run. These submodules must be downloaded manually from their respective repositories and placed in the \Homer3 folder.
+Note that cloning the repository or using the Download .zip button on the repository webpage WILL NOT download the submodule libraries that are a part of Homer3. Without these, the application will not run. These submodules must be downloaded manually from their respective repositories and placed in the \Homer3 folder.
 
 ## Support
-Support for users of Homer3 is available via the [Homer3 & AtlasViewer community forum](https://openfnirs.org/community/homer3-forum/) hosted on openfnirs.org. This forum is questions about how to use Homer3.
+Support for users of Homer3 is available via the [Homer3 & AtlasViewer community forum](https://openfnirs.org/community/homer3-forum/) hosted on openfnirs.org. This forum is for questions about how to use Homer3.
 
 To report a bug or suggest a feature, please [create an issue](https://github.com/BUNPC/Homer3/issues/new/choose) here on GitHub.
 
@@ -28,7 +28,7 @@ Homer3 documentation is hosted via the [GitHub wiki](https://github.com/BUNPC/Ho
 
 ## Contributing to Homer3
 
-We welcome contributions to Homer3 from the fNIRS community. See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines and [WORKFLOW.md](WORKFLOW.md) for a walkthrough of the cloning and version control procedures recommended for development.
+We welcome contributions to Homer3 from the fNIRS community. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for development guidelines and [WORKFLOW.md](.github/WORKFLOW.md) for a walkthrough of the cloning and version control procedures recommended for development.
 
 ## License