Skip to content

dev guide

Jump to bottom
Jian Tay edited this page Jun 15, 2021 · 2 revisions

Welcome to the developer documentation for the Linear Assignment toolbox. This documentation is intended to help developers to understand the code of the toolbox. It is expected that you are familiar with object-oriented programming in MATLAB.

[[TOC]]

Class Documentation

Source Code

The source code for this project is managed using Git and hosted on GitHub.

  1. To get the latest development version of the code, clone the repository using Git
git clone git@github.com:Biofrontiers-ALMC/cell-tracking-toolbox.git
cd lap-cell-tracker
  1. Switch to the development branch
git checkout dev
  1. Add the tbx directory to the MATLAB path
addpath('tbx/')

Directory structure

The toolbox is structured following the Best Practices outlined in this Mathworks Blogs post.

lap-cell-tracker (root)
  |-- build/   - Project file (*.prj) to build the toolbox
  |-- tbx/     - Main toolbox folder
       |-- docs/          - MATLAB documentation
       |-- lap-tracker/   - Classes and code
  |-- tests/   - Testing code

Contributing

We welcome contributions that make the code better. The recommended way to contribute code to the project is by submitting a pull request.

  1. (Optional but recommended) Check for open issues or open a fresh issue for your feature idea or bug.

  2. Create a copy of the project by forking using the GitHub interface on the project page.

  3. Checkout the development branch

    git checkout dev

  4. Switch to a new working branch. You can name it whatever you like.

    git checkout -b my-new-feature

  5. Add your code.

  6. Write a test showing that the bug was fixed or that the feature works as expected.

  7. Once everything is working as expected, add the files and commit to your local repository.

    git add -A
git commit -m 'Fixed an incorrectly named variable in function()'

    Please help us understand what you have changed by writing a descriptive title. If your changes are more extensive, please add a detailed message by running a full commit instead.

    git add -A
git commit

  8. Push your changes to the forked repository

    git push origin my-new-feature

  9. Submit a merge request to the dev branch. A maintainer will then review the code and merge it with the main code if accepted.

Maintainer's guide

This section is for maintainers of the project.

Branch organization

We use the Gitlab flow model to organize the repository. In short, all development occurs on the main dev branch and new feature branches are merged by maintainters into dev. Once enough changes have accumulated, we will create a new release that merges dev into the master branch.

Semantic versioning

Version numbers are created using the semantic versioning specification. Version numbers are MAJOR.MINOR.PATCH.

  • MAJOR versions are incompatible with previous major versions.
  • MINOR versions are backwards compatible with previous versions.
  • PATCH versions are for backwards compatible bug fixes.

Deprecation policy

As the code grows, functions and properties will become deprecated to keep the codebase tidy. When deprecating functions and properties, we will keep compatibility for a major version.

Example workflow for deprecating a function/property:

  • Function is deprecated in version 1.5.0 but is made backwards compatible
  • Warnings are issued in all following versions 1.x.x
  • Functionality and warnings are removed in the next major version release 2.0.0

Building the toolbox

  1. Make sure that the tbx/ folder and all its subfolders are added to the MATLAB path.

  2. Load build/Linear Assignment Cell Tracker.prj in MATLAB's Toolbox Packager tool.

  3. Check that the folders lap-tracker and docs are shown under 'Toolbox Files and Folders'.

  4. Under 'Install Actions', make sure that the following folders are present in the 'MATLAB Path' frame:

     <Toolbox Folder>

    If these folders are missing, check that the /tbx folder and its subfolders are added to the path, then click on Reset to the current MATLAB path.

  5. Click on the Package button on the toolbar.

  6. To test the package, remove the tbx/ folder and all its subfolders. Then run the tests described in the section above.

Tests

As of v2.0.0, the tests are outdated so ignore this section for now. I am reconsidering how unit testing will work in the future. One approach is to avoid unit testing but to evaluate the code by comparing the output against a ground truth dataset.

To ensure compatibility, there are a number of tests that are included in the folder.

To run these tests, use

runtests('testing')

This project also uses tags to group tests into different categories. For more details, consult the Developer's Guide of the Wiki.

Creating a release

Release procedures:

  1. Check that all tests are running
  2. Check that all new methods and properties are properly documented
  3. Check that the wiki is up to date
  4. Merge the dev branch with master 
git checkout master
git merge dev

  1. Resolve any conflicts

  2. Update the Toolbox Project file (*.prj) in the build folder:

    1. The toolbox folder should be set to tbx/.
    2. Increment the version number.
    3. Check that MATLAB path only contains entries starting with <Toolbox Folder>. This avoids unexpected external files to be included.
    4. Check that there are no external files or Java JAR files included.
    5. Update the Platform and Release Compatibility fields as necessary.
    6. Package the toolbox and check that the code runs as expected.

  3. Add all files and commit to master

    git add -A
git commit -m "Updated build to v1.x.x"

  4. Create a new tag

    git tag -a "v1.x.x" -m "Date of release"

  5. Push both the repository and the tag

    git push origin master
git push --tags

  6. Create a Release on GitHub:

    1. Go to Repository > Tags and select Edit Release Notes (pencil This is not optional, it is how GitHub creates releases.
    2. Write the release notes. This should be bulleted list with short tags, e.g. 
      * **New:** New features
* **Fixed:** Fixed bugs
* **Improvement:** Making something user friendly/more accurate
    3. Upload the packaged toolbox (*.mltbx).
    4. Save changes. The new release should now appear under Project Overview > Releases.
Clone this wiki locally