-
Notifications
You must be signed in to change notification settings - Fork 2
Collab_Guidelines
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).
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 thewiki
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. - 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 overallwiki
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 innigeLab
).Home.md
andHome_[page].md
are examples of this naming strategy.-
Direct references to
nigeLab
methods. Please, if a name directly references anigeLab
method, refer to the naming scheme used fornigeLab.md
andnigeLab_Block.md
, etc.
-
Direct references to
-
Modifying an existing
- Once you've made whatever changes you wish to add to the
wiki
, submit a Pull Request from your localwiki
repository. Then we can approve changes and add your contribution to thewiki
. Thanks!
We aren't super strict about coding guidelines, but there are a few practices that we are trying to enforce currently.
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 usingnigeLab.sounds.play('soundFileName');
-
+nigeLab/setup
contains code for installing nigelab and running a demo.
- 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()
)
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.
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.
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).
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.
- 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 intodevelop
first as an "unstable working" version until it has been tested for a while. Once a feature has been working in thedevelop
branch for a while, we will review it to add to the master branch.
- Clone this repository (instead of fork).
- Work as described in steps above.
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.
Any commit that is merged to the master branch must first pass at least one successful code review from @m053m716, @Nabarb, or @sbuccelli.