Contributing
Clone this wiki locally
Contributing
Adding a command
-
Edit
./commands.json
:a. Add the command in the correct alphabetical order to the
commands
array.b. If the command should not be installed globally in the system path with the
cash-global
package (such as the alias command, which would not work), add it to theglobalExclusions
array.c. If the command can be published as its own independent package (i.e.
npm install cash-ls
), add it to thepackages
object, ensuring to list all module and utility dependencies it relies on. Copy
./src/commands/boilerplate.js
and rename it to your exact command name, such asecho.js
.-
Copy an existing test file in
./test/
and rename it to your exact command name. Follow the standard / layout of other existing tests, including:a. One test per feature. Don't jumble a lot of checks into one test description.
b. Test on a gradient, e.g. the command should exist, and then it should do something.
c. Thorough testing - lots of tests to cover every single feature. Test for 100% coverage.
d. Write your tests based on the actual activity of the POSIX-compliant command, not what you would like the command to do.
e. A separate embedded
describe
clause for each option, with one or more tests in each. Follow the boilerplate instructions to build your command.
Edit
./src/help.js
and add the help blurb to thecommands
array.A new help file in
./src/help/
, copying an existing help file as a template. Your help should mirror the other help files, which are roughly based off of the GNU CoreUtils help blurbs. Only include those options and features which have been implemented so far.To transpile your code, run
gulp
in a separate console, which will watch the source directories and rebuild accordingly.Don't hesitate to ask questions, even stupid ones! Your code will be thoroughly scrutinized before being published, but that doesn't mean you should have second thoughts about contributing. We will help you make the perfect implementation of your command and your help is totally appreciated.
Editing existing commands
Want to make a patch or add a feature to an existing command? Here's a brief introduction to the layout:
-
src/commands
: Each command is implemented in a single file. -
src/help
: Each command has a help file in this directory. -
src/util
: Each utility used is implemented in a single file per method, for modularity. -
test
: Each command has a single test file. src/help.js
: Contains a single-line blurb per-command for the overall help.
Edit the command in the
commands
directory.Implement a thorough unit test for every single feature or option added through the
test
directory.Update the file in the
help
directory for any updated / altered functionality.Update the help blurb in
src/help.js
if any options or functionality was added.Run
gulp
to transpile the code and update the related individually published Cash modules.