From a5251f5375cbae9952f86610022a2ad5cf682291 Mon Sep 17 00:00:00 2001 From: labbots Date: Tue, 9 Jun 2020 19:17:26 +0100 Subject: [PATCH] Updated CONTRIBUTING.md --- CONTRIBUTING.md | 111 +++++++++++++++++++++++++++++++++++++++++ bin/generate_readme.sh | 13 +++-- src/misc.sh | 8 ++- 3 files changed, 124 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 58d3faf..6973c93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,3 +2,114 @@ :+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. + +## 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. +- 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 -p 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. diff --git a/bin/generate_readme.sh b/bin/generate_readme.sh index 2c2f34c..fb162bb 100755 --- a/bin/generate_readme.sh +++ b/bin/generate_readme.sh @@ -5,7 +5,7 @@ _usage() { printf " Script to autogenerate markdown based on bash source code.\n -The script generates table of contents and bashdoc and update it the given markdown template.\n +The script generates table of contents and bashdoc and update the given markdown file.\n Usage:\n %s [options.. ]\n Options:\n -f | --file - Relative or absolute path to the README.md file. @@ -18,7 +18,7 @@ Options:\n _setup_arguments() { - unset MINLEVEL MAXLEVEL SCRIPT_FILE SOURCE_MARKDOWN SOURCE_SCRIPT_DIR + unset MINLEVEL MAXLEVEL SCRIPT_FILE SOURCE_MARKDOWN SOURCE_SCRIPT_DIR SCRIPT_DIR MINLEVEL=1 MAXLEVEL=3 SCRIPT_FILE="${0##*/}" @@ -108,6 +108,13 @@ _setup_arguments() { printf "Minimum level for TOC cannot be greater than the depth of TOC to be printed.\n" && exit 1 fi + declare source="${BASH_SOURCE[0]}" + while [ -h "$source" ]; do # resolve $source until the file is no longer a symlink + SCRIPT_DIR="$(cd -P "$(dirname "$source")" > /dev/null 2>&1 && pwd)" + source="$(readlink "$source")" + [[ $source != /* ]] && source="$SCRIPT_DIR/$source" # if $SOURCE was a relative symlink, we need to resolve it relative to the path where the symlink file was located + done + SCRIPT_DIR="$(cd -P "$(dirname "$source")" > /dev/null 2>&1 && pwd)" } _setup_tempfile() { @@ -121,7 +128,7 @@ _generate_shdoc() { declare file file="$(realpath "${1}")" if [[ -s "${file}" ]]; then - ./bashdoc.awk < "${file}" >> "$2" + "${SCRIPT_DIR}"/bashdoc.awk < "${file}" >> "$2" fi } diff --git a/src/misc.sh b/src/misc.sh index 9eacc12..fca9a75 100644 --- a/src/misc.sh +++ b/src/misc.sh @@ -54,8 +54,7 @@ misc::check_internet_connection() { misc::get_pid() { [[ $# = 0 ]] && printf "%s: Missing arguments\n" "${FUNCNAME[0]}" && return 2 - ps -ef | grep "${1}" | grep -v grep | awk '{ print $2; }' - unset psopts + pgrep "${1}" } # @description Get user id based on username. @@ -74,14 +73,14 @@ misc::get_pid() { misc::get_uid() { [[ $# = 0 ]] && printf "%s: Missing arguments\n" "${FUNCNAME[0]}" && return 2 - user_id=$(id ${1} 2> /dev/null) + user_id=$(id "${1}" 2> /dev/null) declare -i ret=$? if [[ $ret -ne 0 ]]; then printf "No user found with username: %s" "${1}\n" return 1 fi - printf "${user_id}\n" | sed -e 's/(.*$//' -e 's/^uid=//' + printf "%s\n" "${user_id}" | sed -e 's/(.*$//' -e 's/^uid=//' unset user_id } @@ -99,7 +98,6 @@ misc::get_uid() { # # @stdout random generated uuid. misc::generate_uuid() { - # Usage: generate_uuid C="89ab" for ((N=0;N<16;++N)); do