Skip to content

Latest commit

 

History

History
129 lines (96 loc) · 5.26 KB

CONTRIBUTING.md

File metadata and controls

129 lines (96 loc) · 5.26 KB
Raw

Contributing to Bash-Utility

👍🎉 First off, thanks for taking the time to contribute! 🎉👍 The following is a set of guidelines for contributing to this project on GitHub. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

Table of Contents

Code Contributions

Great, the more, the merrier.

Sane code contributions are always welcome, whether to the code or documentation.

Before making a pull request, make sure to follow below guidelines:

Code Guidelines

Styleguide

  • Variable names must be meaningful and self-documenting.

  • Long variable names must be structured by underscores to improve legibility.

  • Global variables and constants must be ALL CAPS with underscores. (eg., INPUT_FILE)

  • local variables used within functions must be all lower case with underscores ( only if required ). (eg., input_data)

  • Variable names can be alphanumeric with underscores. No special characters in variable names.

  • Variables name must not start with number.

  • Variables within function must be declared. So the scope of variable is restricted to the function.

  • Avoid accessing global variables within functions.

  • Function names must be all lower case with underscores to seperate words (snake_case).

  • Function name must start with section name followed by 2 colons and then the function name (eg., array::contains())

  • Try using bash builtins and string substitution as much as possible.

  • Use printf everywhere instead of echo.

  • Before adding a new logic, be sure to check the existing code.

  • Make sure to add the function in appropriate section based on its operation.

  • Use shfmt to format the script. Use below command:

     shfmt upload.sh

    The repo already provides the .editorconfig file, which shfmt reads, so no need for extra flags. You can also install shfmt for various editors, refer their repo for information. Note: This is strictly necessary to maintain consistency, do not skip.

  • Script should pass all shellcheck warnings, if not, then disable the warning and give a valid reason.

Bashdoc guideline

The documentation is generated based on the function documentation within the script file. So ensure to follow the style so the documentation is properly generated by the generator.

Follow the below bashdoc template to add function introductory comment.

# @description Multiline description goes here and
# there
#
# @example
#   sample::function a b c
#   echo 123
#
# @arg $1 string Some arg.
# @arg $2 any Rest of arguments.
#
# @noargs
#
# @exitcode 0  If successfull.
# @exitcode >0 On failure
# @exitcode 5  On some error.
#
# @stdout Path to something.
#
# @see sample::other_function(()
sample::function() {
}
  • Each function must have a description detailing what the function does and a sample usage example to show how the function can be used.
  • specify whether the function accepts args or no args by specifying @arg or @noargs tag in the comment.
  • Make sure to document the exitcode emitted by the function.
  • If the function is similar to other function add a reference to function using @see tag.

Documentation

  • Refrain from making unnecessary newlines or whitespace.

  • Use pure markdown as much as possible, html is accepted but shouldn't be a priority.

  • The markdown must pass RemarkLint checks.

  • The function documentation and Table of Content is autogenerated using generate_readme.sh. So DO NOT edit them manually. Use the following command to update ToC and Bashdoc.

    ./bin/generate_readme.sh -f README.md -s src/

Commit Guidelines

It is recommended to use small commits over one large commit. Small, focused commits make the review process easier and are more likely to be accepted.

It is also important to summarise the changes made with brief commit messages. If the commit fixes a specific issue, it is also good to note that in the commit message.

The commit message should start with a single line that briefly describes the changes. That should be followed by a blank line and then a more detailed explanation.

Before committing check for unnecessary whitespace with git diff --check.

Pull Request Guidelines

The following guidelines will increase the likelihood that your pull request will get accepted:

  • Follow the commit and code guidelines.
  • Keep the patches on topic and focused.
  • Try to avoid unnecessary formatting and clean-up where reasonable.

A pull request should contain the following:

  • At least one commit (all of which should follow the Commit Guidelines).
  • Title that summarises the issue/feature.
  • Description that briefly summarises the changes.

After submitting a pull request, you should get a response within 7 days. If you do not, don't hesitate to ping the thread.

Contact

For further inquiries, you can contact the developer by opening an issue on the repository.