Skip to content

Latest commit

 

History

History
89 lines (53 loc) · 6.61 KB

CONTRIBUTING.md

File metadata and controls

89 lines (53 loc) · 6.61 KB
Raw

Contributing

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.

Release and versioning procedures

Homer3 releases are composed of frozen source code from the master branch of this repository plus compiled versions of the software for use with the MATLAB Runtime 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, i.e. v1.32.3.

For releases which contain only fixes to the previous release, the third value vX.X.X is to be incremented.

For releases combining many fixes or a release which adds additional features to Homer3, the second value vX.X.X is to be incremented.

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 and therefore the code itself 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.

Fork and pull model

Following the fork and pull model, contributors are expected to make their changes in their fork of the repository and to create pull requests 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 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
  • 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 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 related to a feature branch can help to facilitate discussion about collaborative development.

Shared Libraries

Homer3 and AtlasViewer contain shared code including the Utils and DataTree modules. To operate both apps from the same MATLAB instance simultaneously, setpaths populates the MATLAB path. To avoid clobbering functions or objects, we endeavor to keep the shared code similar.

As of February 2022, Homer3 and AtlasViewer no longer use the Git submodule utility. The standalone repositoties still exist, but now Homer3 and AtlasViewer contain copies of the standalone repos. The file .gitmodules still exists to specify what code in Homer3 and AtlasViwer is shared libraries; that is, what code has a corresponding standalone repos as its source. The file .gitmodules is used by internal utilities that can be run to update Homer3 and AtlasViwer versions of the libraries and insure that they match the lastest standaone version.

To keep Homer3 in step with its submodule repositories:

  1. Make changes in Homer3 (and its copy of the shared code)
  2. Commit & push changes to a fork of Homer3.
  3. Open pull request to integrate with BUNPC:Homer3 and link to PR created in Step 6 below.
  4. Set up local Homer3/ to track fork of shared module, i.e. DataTree
cd Homer3/DataTree
git init
git remote add origin https://github.com/jayd1860/DataTree
git fetch
git reset --mixed origin
  1. Commit & push changes to a fork of shared module
  2. Open pull request to integrate with BUNPC:<shared module>, and link to PR in Step 3 above.

Development environment

An intallation of Git is required.

GitHub Desktop, Visual Studio Code, and TortoiseSVN are popular GUI applications for version control. **While these applications are very useful for visualizing changes to files and resolving merge conflicts, familiarity with the git CLI is strongly recommended.

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.

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.

We compile these releases for Windows and MacOS. Linux is not supported.

Walkthrough

A step-by-step walkthrough of key steps in the version control process is described in WORKFLOW.md.