mirror of
https://github.com/armbian/bash-util.git
synced 2026-01-06 10:37:49 -08:00
130 lines
5.3 KiB
Markdown
130 lines
5.3 KiB
Markdown
# Contributing to Bash-Utility
|
|
|
|
:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
|
|
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](#code-contributions)
|
|
- [Code Guidelines](#code-guidelines)
|
|
- [Styleguide](#styleguide)
|
|
- [Bashdoc guideline](#bashdoc-guideline)
|
|
- [Documentation](#documentation)
|
|
- [Commit Guidelines](#commit-guidelines)
|
|
- [Pull Request Guidelines](#pull-request-guidelines)
|
|
- [Contact](#contact)
|
|
|
|
## 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](https://github.com/mvdan/sh) to format the script. Use below command:
|
|
|
|
```shell
|
|
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](https://www.shellcheck.net/) 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.
|
|
|
|
```bash
|
|
# @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.
|
|
|
|
```bash
|
|
./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.
|