Contributing

Contributing

Adding a command

1. 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 the globalExclusions array.

   c. If the command can be published as its own independent package (i.e. npm install cash-ls), add it to the packages object, ensuring to list all module and utility dependencies it relies on.

2. Copy ./src/commands/boilerplate.js and rename it to your exact command name, such as echo.js.

3. 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.

4. Follow the boilerplate instructions to build your command.

5. Edit ./src/help.js and add the help blurb to the commands array.

6. 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.

7. To transpile your code, run gulp in a separate console, which will watch the source directories and rebuild accordingly.

8. 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.

1. Edit the command in the commands directory.

2. Implement a thorough unit test for every single feature or option added through the test directory.

3. Update the file in the help directory for any updated / altered functionality.

4. Update the help blurb in src/help.js if any options or functionality was added.

5. Run gulp to transpile the code and update the related individually published Cash modules.