Collab_Guidelines

Contributing

Part of the impetus behind developing nigeLab was to facilitate the exchange of analytical techniques between members of the KUMC and IIT groups. Having a unified framework for development would mean that analyses would be more reproducible, without multiple engineers re-inventing the same methods, while simultaneously providing a good on-boarding tool for new students.

We are more than happy for others to contribute to nigeLab. The following are standards and practices we have established, so if you would like to contribute, please try to adhere to the conventions described below (otherwise Nigel gets grumpy).

`Wiki`

The easiest way to contribute is by adding to this wiki, particularly if you don't want to mess around with the code. This will be particularly helpful as nigeLab gets off the ground, when the first users are experimenting with getting their own work-flow up and running. A particularly helpful area to expand on would be by adding concrete work-flow examples, which should then be linked to from Walkthroughs.

To help out with the wiki, take the following steps:

Clone this wiki locally. You should end up with a folder that has all the wiki pages in it as *.md files, with that folder ending in .wiki.
- We recommend using GitKraken as a Git user-interface, since it has a fun squid icon.
(Optional) You might want to download a text editor that makes previewing the wiki edits in *.md easier, if you don't have one.
- We recommend using Typora, then opening the .wiki folder so you can see all the pages as files in the navbar on the left.
- Having an editor like Typora will also make it easier to check links, preview formatting, etc.
Depending on what you're doing:
- Modifying an existing wiki page. If you are making modifications to an existing page, then just open that *.md file, add changes, and save it.
- Creating a new wiki page. Simply create the new page as a *.md file. When considering the page name, which will serve as a means to link that page to the overall wiki structure, please consider using a "hierarchical" naming convention. For example, if it will be linked in the Side navigation bar (_Sidebar.md), then consider a nested naming convention depending on the section it's going under. "Nesting" for file names of .wiki pages uses the _ delimiter (like a lot of things in nigeLab). Home.md and Home_[page].md are examples of this naming strategy.
  - Direct references to nigeLab methods. Please, if a name directly references a nigeLab method, refer to the naming scheme used for nigeLab.md and nigeLab_Block.md, etc.
Once you've made whatever changes you wish to add to the wiki, submit a Pull Request from your local wiki repository. Then we can approve changes and add your contribution to the wiki. Thanks!

`Code`

We aren't super strict about coding guidelines, but there are a few practices that we are trying to enforce currently.

What Goes Where?

Contributions are most likely going to go as a method under the Block, Animal, or Tank classes (or, preferably, all three). The other folders contain:

+nigeLab/+evt is for custom eventData that might be useful for various listeners.
+nigeLab/+libs is for libraries that are helpful to the main classes, but which shouldn't be at the main level of the package as they won't be called on their own very often.
+nigeLab/+utils is similar to +nigeLab/+libs, but is for utilities that might be more generic than the helper functions in +nigeLab/+libs.
+nigeLab/+sounds is where custom sounds (for example different kinds of notifications) can be placed and then accessed using nigeLab.sounds.play('soundFileName');
+nigeLab/setup contains code for installing nigelab and running a demo.

Capitalization

Methods & Functions are generally camel-case, with the first letter always lower-case (e.g. linkADC(blockObj)).
Inside the code, variables are generally lower-case, but there might be a mixture of lower-case-starting variables that have camel-case due to not establishing conventions immediately. Matrices tend to be single (capital) letters.
Class Properties & Functions in +defaults start with upper-case letters (e.g. nigeLab.Block())

Commenting Structure

We understand this is not always possible, for example with @Nabarb, when only the threat of physical violence will make code comprehensible. All joking aside, while not required, a suggested template for methods is as follows:

function out = myFunction(in,varargin)
%% MYFUNCTION	Helper function to add comments to other functions.
%
%	out = MYFUNCTION(in);
%	out = MYFUNCTION(in,'NAME',value,...);
%
%  --------
%   INPUTS
%  --------
%     in          :     Function handle to poorly-documented function.
%
%
%  varargin       :     (Optional) 'NAME', value input argument pairs.
%
%  --------
%   OUTPUT
%  --------
%    out          :     Function handle to new-and-improved commented function.
%
%
% By: Freddy Barban  v1.0  MM/DD/YYYY  Original Version (R2017a)

Formatting in this way works well with the existing Matlab help and doc commands.

Small Chunks Please

Ideally, a method deals with one small functionality so that the inputs and outputs are easily understood, making the code easier to organize and debug. @m053m716 far and away prefers to do pull request reviews on many small commits than on large chunks of complicated code.

Hard-Coded Parameters in +defaults

Any hard-coded parameter that is used should go in the associated function within +nigeLab/+defaults. For example, the decimation and interpolation values for the cascaded filters applied to downsample LFP data are in +nigeLab/+defaults/LFP.m.

Any file in +defaults should return a struct, pars, which has the relevant (descriptive) field name that corresponds to the variable that would otherwise be hard-coded. This way, it is easy for users to change the "configuration" by changing hard-coded values that should all reside in one place (the +defaults folder).

`GitHub`

Issues

If you are unsure whether to contribute, or have any questions, please submit an Issue. Likewise, if you find a BUG in our code, please let us know by submitting a bug report.

How to contribute (external)

Fork this repository.
Make a branch with the naming convention feature/thingYouAreAdding
Add whatever thing you want to this branch.
When you are done, issue a Pull Request to the develop branch for your branch. Code goes into develop first as an "unstable working" version until it has been tested for a while. Once a feature has been working in the develop branch for a while, we will review it to add to the master branch.

How to contribute (internal collaborators)

Clone this repository (instead of fork).
Work as described in steps above.

Hotfixes

There will probably be bugs for code in the develop branch, since it may not be tested for all systems or workflows initially by whomever contributes it. To fix bugs in develop branch directly (without a new feature branch), make a sub-branch develop/bugIdentifier with something that generically identifies the bug. Once you have fixed the bug, issue a pull request to merge back into develop as described above.