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.
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.
## 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.
In most cases, changes should be made to the [development branch](https://github.com/BUNPC/Homer3/tree/development) of the repository.
### Pull requests
Open a pull request via the Contribute button on your fork's page.
Pull requests must meet the following requirements:
- Pull requests must not include erroneous files or whitespace changes
- 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
### 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 `development` branch integrates finished features and fixes. The development branch is synced with the master branch periodically.
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
As of October 2021, code shared with other applications in the openfnirs ecosystem such as the [DataTree](https://github.com/BUNPC/DataTree) and [Utils](https://github.com/BUNPC/Utils) libraries are managed as [submodule repositories](https://git-scm.com/book/en/v2/Git-Tools-Submodules). Submodules cannot be managed using GitHub desktop.
Contributing to submodules is mostly equivalent to contributing to the Homer3 repository. Take care to ensure that submodules changes are compatible with Homer3 and AtlasViewer by avoiding changes to interfaces and names.
If you have made combined changes to the submodule as well as Homer3, explicitly link the submodule PR to the related PR in the parent repository. The submodule PR must be accepted before the PR can be accepted in the parent repository.
## Development environment
An [intallation of Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) is required.
[GitHub Desktop](https://desktop.github.com/), [Visual Studio Code](https://code.visualstudio.com/), and [TortoiseSVN](https://tortoisesvn.net/) are popular GUI applications for version control. **While these applications are very useful for visualizing changes to files and resolving merge conflicts, please note that these applications offer only modest support for git submodules.** The use of command line git for management of submodules is highly recommended; see the example below.
### MATLAB Version
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.
The use of 2017b is therefore recommended for development purposes.
## Walkthrough
A step-by-step walkthrough of key steps in the version control process is described in [WORKFLOW.md](WORKFLOW.md).
Homer3 is a MATLAB application used for analyzing fNIRS data to obtain estimates and maps of brain activation. It is a continuation of the work on the well-established HOMER2 software which itself evolved since the early 1990s, first as the Photon Migration Imaging Toolbox, then HOMER and HOMER2.
Homer3 is a open source MATLAB application used for analyzing fNIRS data to obtain estimates and maps of brain activation. It is a continuation of the work on the well-established HOMER2 software which itself evolved since the early 1990s, first as the Photon Migration Imaging Toolbox, then as HOMER.
Homer3 is developed and maintained by the [Boston University Neurophotonics Center](http://www.bu.edu/neurophotonics/).
*[Homer3 Community & Support Forum](https://openfnirs.org/community/homer3-forum/)
To cite Homer3 in your research:
> #### Huppert, T., Diamond, S., Franceschini, M., Boas, D. (2009). HomER: a review of time-series analysis methods for near-infrared spectroscopy of the brain. Applied optics 48(10). https://dx.doi.org/10.1364/ao.48.00d280
## Installation
Homer3 is composed only of MATLAB scripts, so the installation process for MATLAB users is as simple as downloading the code.
[Get the latest release of Homer3](https://github.com/BUNPC/Homer3/releases/latest/)
[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.
## 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.
To report a bug or suggest a feature, please [create an issue](https://github.com/BUNPC/Homer3/issues/new/choose) here on GitHub.
## Documentation
Homer3 documentation is hosted via the [GitHub wiki](https://github.com/BUNPC/Homer3/wiki) and is a work in progress.
## Contributing to Homer3
We welcome contributions to Homer3 from the fNIRS community. See CONTRIBUTING.md for development guidelines and WORKFLOW.md for a walkthrough of the cloning and version control procedures recommended for development.
## License
Homer3 is [BSD licensed](https://opensource.org/licenses/BSD-3-Clause), but we ask that you cite the original publication in your research.
The following is an example of the fork and pull workflow, making use of the git command line interface. Users of alternative graphical interfaces are responsible for learning how to achieve equivalent functionality!
**Please follow along with this when contributing if you are only an entry-level user of Git!**
## Forking Homer3
A fork is a complete copy of a repository. Regular contributors should maintain their own fork of Homer3.
To create a fork, click the Fork button on the top right of the repository page.
If you intend to contribute to Homer3's submodules, repeat this process for these repositories as well.
## Cloning your fork of Homer3
To clone the repository is to download the *remote* repository (the code hosted on GitHub) to your local machine.
To clone Homer3 along with all its submodules, use
A simple `git clone` without the `--recurse-submodules` parameter WILL NOT download the associated submodules, nor using the Download button on the repository webpage.
### Switching to the working branch
If you intend to edit a single branch of your fork, a convenient parameter is `--single-branch`:
To confirm that the submodules are now part of your branch:
```shell
cd <name of submodule>
git status
```
The submodule should be treated as its own repository from this point o\
nward. For the remainder of the tutorial, remember that each section must be repeated within the submodules up until the point at which pull requests are created. **Do not commit your changes to `.gitmodules`**.
## Syncing your fork with the BUNPC repository
If you want to download the latest code from the BUNPC repository before making your changes or before opening a pull request, you will need to link your local repository to the original remote. From inside the cloned /Homer3 folder:
Now you can sync the working branch of your local repository with the current state of the branch you ultimately want to contribute to, such as BUNPC/development:
```shell
git pull bunpc development --recurse-submodules
```
This will fetch and merge the remote branch `development` from the BUNPC respository. If problems arise, you will have to resolve the merge conflicts manually. Resolving conflicts is [possible via the Git command line interface](https://docs.github.com/en/github/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line), but made easier with graphical utilities such as [GitHub Desktop](https://desktop.github.com/), [Visual Studio Code](https://code.visualstudio.com/), or [TortoiseSVN](https://tortoisesvn.net/).
To undo a merge that has gone awry, use
```shell
git merge --abort
```
> Note: pulling the latest remote branch and resolving conflicts is required before opening a pull request.
## Committing changes
Changes you have made must deliberately committed to the working branch.
To see the list of files which have been changed:
```shell
git status
```
> Note: Graphical interfaces can make staging files for commits more intuitive.
To add files to a commit using the command line:
```shell
git add <name of file>
```
Once changes have been staged, commit them using
```shell
git commit -m <description of the changes being committed>
```
To commit files to a submodule, change directories to the submodule and repeat the process of adding files and committing changes.
> Note: take care not to accidentally add log files, configuration files like AppSettings.cfg, or generated data such as Registry.mat to your commits.
To push your commits to your remote fork:
```shell
git push origin <working branch name>
```
## Creating a pull request
Create a pull request in the Pull Request tab of the repository website or via the Contribute button. Target the head branch you wish to contribute to, i.e. `development`.
If there is a conflict, follow the above instructions for [Syncing your fork with the BUNPC repository](Syncing-your-fork-with-the-BUNPC-repository) and resolve the conflict locally by pushing a merge commit to your working branch.
See [CONTRIBUTING.md](CONTRIBUTING.md) for expectations regarding pull requests.
