dev guide

Developer's Guide

If you are wanting to contribute to the CyAn project, please review this Guide. If you are wanting to use the toolbox, please consult the user guide instead.

Source code

The source code is managed using Git and hosted on biof-git

git clone [email protected]:cameron-lab/cyanobacteria-toolbox.git

Bug Reports and Feature Requests

If you have encountered a problem with the toolbox or have an idea for new features, please submit a ticket to the Issue Tracker or send us a ticket at [email protected].

For bug reports, please provide enough details to reproduce the error, including details of external files used. If possible, please include a minimal example that produces the error and post that. Please also include the full error message at the end of the report.

Contributing to the project

To contribute to this project, you should know how to use Git.

Branch organization

We use a simple branch organization based of Gitlab Flow. The repository only contains two branches:

• master - Stable code that is packaged into a MATLAB toolbox
• dev - Latest code. You should always start with this branch.

Workflow

We use a branching strategy to handle code merges. In short, to contribute code, you should be writing your code in a new feature branch. The branch can be pushed to the public repository. When your code is ready, create a merge request for review by a Maintainer.

Here are more detailed steps:

1. Clone the repository to your computer

   git clone [email protected]:cameron-lab/cyanobacteria-toolbox.git
   cd cyanobacteria-toolbox
   

2. Checkout the development branch

   git checkout dev
   

3. Create a new local feature branch. Please name the branch with the new changes or fixes you are trying to make.

   git checkout -b my-new-feature
   

4. Write your code, committing and pushing as necessary. It is a good idea to check and merge changes from the dev branch frequently.

   git checkout dev
   git pull
   git checkout my-new-feature
   git merge dev
   

5. When your code is ready to be merged, check that your branch is up-to-date with the main repository, then make a final commit.

   git checkout dev
   git pull
   git checkout my-new-feature
   git merge dev
   git add -A
   git commit
   

6. Push your branch to the repository

   git push
   

7. Create a merge request:

   1. Go to the project page
   2. Select Repository > Branches, then click on your branch name
   3. Click on the Create merge request button (see here)

   Fill in the title and description. Please help us understand what you have changed by writing a descriptive title, as well as bullet points explaining the changes. A good example would be:

   Title: Added capability to measure line centroids
   
   * New: Method getLineData() in CyTracker. This method will measure the 
     center position of a line 
   * Improved: Position coordinates are now in microns rather than pixels
   

8. Submit the request and wait for a Maintainer to approve your code!

Documenting new features

If you are adding a new feature (e.g. a new method or function), please add help documentation using MATLAB's help formatting. This documentation will be used to generate corresponding help documents in the wiki.

Adding new segmentation code

In general, new segmentation code should only be added to this project if the code has been tested and found to be of use in multiple projects. Otherwise, the code likely belongs in its own project repository.

When adding new segmentation code, you must document how the algorithm works on the [cell segmentation algorithms] page.