Updated CONTRIBUTING.md

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.

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 <filename.md> - 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
 }
 

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