Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
874 lines (491 loc) · 25.7 KB

CONTRIBUTING.md

File metadata and controls

874 lines (491 loc) · 25.7 KB

Contributing to Git Utilities

Thanks for even thinking about it!

As this Organization grows portions of this document may be moved to GitHub Pages; the text within this document are not set in stone rules but guidelines, and much like other files maintained by this Organization the following may be edited via a Pull Request.

Table of Contents

Code of Conduct

TLDR This Organization is a semiprofessional public place, Treat others as though they have access to your toothbrush, and Code and Facts should be seasoned with Levity and Tact. Review the full-length version if so inclined.

How to Contribute

The goal is, as always, useful code and documentation, though Support is always appreciated. Sharing Repositories maintained by this Organization is an excellent way to contribute if none of the following options are applicable, because the more eyes on a Code Base the more likely it seems that bugs will be found and fixed.

Open Issues

Join the Contributors issuing Pull Requests that close available Open Issues. New Issues may be opened for Reporting Bugs and Suggesting Enhancements. General tips on formatting MarkDown guidelines from this document are advisable to follow. However, please search for existing similar Issues first; example search for memory-leaks from the git-shell-commands repository.

Report Bugs

The bug_report.md Template should when opening a New Issue. Please be detailed and try to include all relevant information within the OP (Original Post). Additionally, if clarifications or more information is requested or discovered, then editing the OP is preferred to adding another post or opening a new issue.

Bugs may also be reported via a Pull Request that suggests fixes, in which case skip opening an Issue and instead use the :bug: emoji as the first word of the fix commit.

Example Bug Report Pull Request

git checkout master
git merge --strategy-option theirs --squash dev-master


git commit -F- <<'EOF'
:bug: memory leak `cow_bell(solo_count_down)` when `solo_count_down=<NaN>`



**Fixes**


- `new-script.sh` file, fixes `cow_bell(solo_count_down)` being called before previous solo has ended

- `README.md` file, removes warnings about excessive cow_bell solos causing memory leaks
EOF


git push forked master

Suggest Enhancements

The feature_request.md Template may be used when opening a New Issue. Whenever possible provide example/pseudo code along with a detailed description of what needs solved. Or in other-words; napkin-sketches are permitted if it helps readers better understand the scope.

Or for faster consideration and adoption of new code, try adding new features via a Pull Request

Example Enhancement Pull Request

git checkout gh-pages
git merge --strategy-option theirs --squash dev-gh-pages


git commit -F- <<'EOF'
:apple: Cow Bell solos supported on Mac OS



**Additions**


`new-script.sh` file;


- feature detection for Mac OS, uses default media player for solos

- feature detection for MS, however requires Bash sub-system to be installed
EOF


git push forked gh-pages

Style Guidelines

One does not have to use all of the following and this is intended to help keep things consistent between all repositories maintained by this Organization. Or in other-words, no-one should get offended if a new line is forgotten or similar, but please do not break anything when issuing Pull Requests.

  • Code that operates as intended is as important as documentation that is comprehensible, so do not sacrifice readability for anything

  • In most cases two (2) should blank lines be used between sections, one (1) between sub-sections, and three (3) between headers and footers or boilerplate sections

  • URLs may break column width limits

  • Tabs shall be a sequence of two spaces ( ), generally no literal tabs (\t) will be permitted within code or documentation

  • Project, File, and Directory names should be lowercase, with hyphens (-) in place of spaces ( ) except where GitHub requires otherwise

  • Documentation should be no more than 1024 lines per file

  • Code specific (.sh) files should aim for less than 512 lines of actionable code, and doc-strings/comments should not exceed 20% of total lines within such files

  • Unix-ish new-lines (\n) are to be used within all files, Pull Request using other line-breaks will be rejected until corrected

Scripting Style Guidelines

  • Lines should not exceed 120 columns wide for code and no more than 80 columns wide for comment blocks

  • Comments in most cases should precede code

  • Variable and function names should be descriptive and underscores (_) in place of spaces ( ) or hyphens (-) between words, please do not issue Pull Requests with camelCased names

  • Use declare -g sparingly, and local variable assignments where necessary

  • Return something from Functions even if that is a boolean status of success or failure

  • Properly handle errors and/or allow errors to bubble up, ask permission when necessary, and fail fast

  • continue past non-matches within loops to avoid over-nesting of conditional logic

shared-functions/modules/git-shell-commands/help

#!/usr/bin/env bash

__SOURCE__="${BASH_SOURCE[0]}"
while [[ -h "${__SOURCE__}" ]]; do
    __SOURCE__="$(find "${__SOURCE__}" -type l -ls | sed -n 's@^.* -> \(.*\)@\1@p')"
done
__DIR__="$(cd -P "$(dirname "${__SOURCE__}")" && pwd)"
__NAME__="${__SOURCE__##*/}"
__AUTHOR__='S0AndS0'
__DESCRIPTION__='Prints help message and commands for more help'


## Provides 'failure'
source "${__DIR__}/shared_functions/modules/trap-failure/failure.sh"
trap 'failure "LINENO" "BASH_LINENO" "${BASH_COMMAND}" "${?}"' ERR

## Provides: argument_parser <arg-array-reference> <acceptable-arg-reference>
source "${__DIR__}/shared_functions/modules/argument-parser/argument_parser.sh"

## Provides: __license__ <description> <author>
source "${__DIR__}/shared_functions/license"


usage(){
    local _message="${1}"
    local _script_name="${_script_name:-${__NAME__}}"

    _script_name="${_script_name##*/}"
    _script_name="${_script_name##*..}"

    local _script_path="${__DIR__}/${_script_name}"
    if [[ "${_script_name}" == "${__NAME__}" ]]; then
        cat <<EOF
## Usage
# ssh ${USER}@host-or-ip ${__NAME__} ${_script_name}
#
# ${__DESCRIPTION__}
#
# ${_script_name}
#  Name of script to run "--help" with
#
# -l --license
# Shows script or project license then exits
#
# -h    --help help
#  Displays this message and exits
EOF
elif [ -f "${_script_path}" ] && [ -e "${_script_path}" ]; then
        printf '%s --help' "${_script_name}"
        "${_script_path}" --help
        local _exit_status="${?}"
    else
        printf 'Error finding help for %s\n' "${_script_name}" >&2
        local _exit_status="1"
    fi

    if [ -n "${_message}" ] && [[ "${_message}" != '0' ]]; then
        printf 'Error - %s\n' "${_message}" >&2
    fi
    return "${_exit_status}"
}

_args=("${@:?# No arguments provided try: ${__NAME__} help}")
_valid_args=('--help|-h|help:bool'
             '--license|-l|license:bool'
             '--script-name:posix-nil')
argument_parser '_args' '_valid_args'
_exit_status="${?}"


if ((_license)); then
    __license__ "${__DESCRIPTION__}" "${__AUTHOR__}"
    exit 0
fi
usage "${_exit_status}"
exit "${_exit_status}"

MarkDown Style Guidelines

  • There is no set column width limits for MarkDown files, but do not get carried away because the focus should be on getting readers up to speed

  • External links are permitted but try to keep it to a minimum; instead refer to built-in man and/or help documentation wherever possible

  • Relative links to other files or locations within documentation is preferred; except for cross-branch linking in which case absolute links are preferred

    • Links be should organized into a Links Section bellow the Content, after three (3) blank lines
    • Link Names should use two underscores between base location and file or title

  • Lists should have one blank line between first layer of items

    • Inner lists should be tabbed in by two (2) spaces and have no blank lines between items of the same level
    • Nesting lists beyond one layer is discouraged and information should be restructured when it becomes tempting to do otherwise

  • Provide a Table of Contents section when headings become numerous and use three underscores (___) as Dividers between main sections

    • Each heading should have an internal MarkDown tag, see following example, used for linking within the document
    • Only one level one heading (lines prefixed with a single # one hash-sign) may be included in a MarkDown document and only when no FrontMatter defines a title: property
    • Main Sections should have a level two heading (prefixed by ## two hash-signs)
    • Sub-Sections should have a level three heading, and nesting beyond this is discouraged

  • Code Blocks should have the related language defined as proper nouns, eg. Bash not bash

    • Formatting within code blocks should follow related guidelines for that language
    • Code blocks should not exceed 120 lines in length
    • Use links to files instead of copying files into Code Blocks
    • Title code blocks with bold back-ticks and example path for re-use elsewhere within documentation...
**`file-name.ext`**

  • Two blank lines should go between Sections, Sub-Sections, Dividers, Code Blocks, and List Blocks.

  • Three blank lines should go between Description, and between Content and Links Section

readme.md

# Title of Document


Short description about content of document, project, and/or code



------


#### Table of Contents


- [First][heading__first_section]

- [Second][heading__second_section]

  - [Bash Time][heading__bash_time]
  - [Bash Variables][heading__bash_variables]

- [End][heading__end_section]


------


## First Section
[heading__first_section]:
  #first-section
  "Link hover-text for first section"


A thing or two about `git`...


\```Bash
_name='S0AndS0'
_repo='.github'

git clone git@github.com:${_name}/${_repo}.git
\```


Maybe a table with some columns to organize something...


| Column One | Column Two |
|------------|------------|
| cell       | cell       |
| cell       | cell       |


___


## Second Section
[heading__second_section]:
  #second-section
  "Link hover-text for second section"


Some notes about _`Bash`_


### Bash Time
[heading__bash_time]:
  #bash-time
  "Link hover-text for Bash time"


**[`time-stamp-date.sh`][branch__current__another_file]**


\```Bash
time_stamp_date() {
  local _date="${1:-$(date)}"
  printf '%s\n' "$(date --date="${_date}" +'%Y%m%d')"
}
\```


### Bash Variables
[heading__bash_variables]:
  #bash-variables
  "Link hover-text for Bash variables"


Interactive console examples...

\```Bash
_now_time_stamp="$(time_stamp_date)"
printf '%s\n' "${_now_time_stamp}"
#> 20191125


_past_time_stamp="$(time_stamp_date 'July 01, 1970')"
printf '%s\n' "${_past_time_stamp}"
#> 19700701
\```


___


## End Section
[heading__end_section]:
  #end-section
  "Link hover-text for end section"


In summation this is the general outline of MarkDown formatting.


Check [`gh-pages`][branch__gh_pages] branch for example usage and documentation.


See [Somewhere Else][example__somewhere_else] for more details on something else.



[branch__current__another_file]: time-stamp-date.sh


[branch__gh_pages]: https://github.com/bash-utilizes/project-name/tree/gh-pages


[example__somewhere_else]: https://example.com/somewhere-else.html

Note, any prefixed back-slashes (\ ) should be removed from above example

Local Development Setup

For repositories that include a _config.yml file within a gh-pages branch then Jekyll is required for building documentation, see the Jekyll Admin for setup and automation scripts built to make such setup tasks a little swifter.

Linux Development Setup

The following steps and variable usage may also work on Mac, and may be Windows if a Bash shell is available.

Shared Variables

_git_name='your-name'
_organization='git-utilities'
_repository='project-name'


_https_origin_url="https://github.com/${_organization}/${_repository}.git"
_git_origin_url="git@github.com:${_organization}/${_repository}.git"
_https_fork_url="https://github.com/${_git_name}/${_repository}.git"
_git_fork_url="git@github.com:${_git_name}/${_repository}.git"

The above Bash variables will be referenced within following sub-sections, modify the values to suite the Forked Repository.

Setup remotes via one of the following;

  1. Make a directory path for Git sources and change directories

  2. Clone fork, checkout gh-pages or example branch, and setup origin tracking

  3. Setup tracking of fork HTTPS URL tracking from perspective of project root

  4. Setup tracking of fork Git URL tracking from perspective of submodule root

mkdir -vp "${HOME}/github/${_git_name}"
cd "${HOME}/github/${_git_name}"


git clone --origin forked "${_git_fork_url}"
cd "${_repository}"
git checkout gh-pages
git remote add origin "${_git_origin_url}"


git config --file=.gitmodules submodule.browser-storage.url "${_https_fork_url}"
git submodule sync
git submodule update --init --recursive --remote


cd "modules/${_repository}"
git remote add forked "${_git_fork_url}"
git fetch forked
git branch --set-upstream-to=forked/master

git push forked master should push to the forked repository URL, and git fetch origin master will download any updates from this Organization. If any updates where downloaded then be sure to merge before issuing a Pull Request.

Windows Development Setup

Batch Variables

set _git_name='your-name'
set _organization='git-utilities'
set _repository='project-name'

set _https_origin_url="https://github.com/%_organization/%_repository.git"
set _git_origin_url="git@github.com:%_organization/%_repository.git"
set _https_fork_url="https://github.com/${_git_name}/${_repository}.git"
set _git_fork_url="git@github.com:%_git_name/%_repository.git"

Batch Git Commands

setlocal enableextensions enabledelayedexpansion


md %HOMEDRIVE%%HOMEPATH%\github\%_git_name
cd %HOMEDRIVE%%HOMEPATH%\github\%_git_name


git clone --origin forked %_git_fork_url
cd %_repository
git checkout gh-pages
git remote add origin %_git_origin_url


git config --file=.gitmodules submodule.browser-storage.url %_https_fork_url
git submodule sync
git submodule update --init --recursive --remote

cd modules\%_repository
git remote add forked %_git_fork_url
git fetch forked
git branch --set-upstream-to=forked/master

Pull Requests are most welcome for correcting anything that might be erroneous.

Git Tips

This will not be an in-depth or exhaustive guide on git usage, as the preexisting documentation available via commands such as git help and git help submodule are thorough.

Git Commit Tips

  • First line should not exceed 74 columns wide and punctuation such as apostrophes, quotes, and periods ("'.") should be avoided

  • First line should be separated from message content by three blank lines

  • While not required the following emoji may be used as the first word of commit messages

    • 🎉 :tada: for Initial Commit of repository, not to be used when re-naming files

    • 📝 :memo: for documentation, new file or content, related commits

    • 🎨 :art: for format and/or structure related changes

    • 🐚 :shell: for script specific changes

    • 🔥 :fire: for deletion of files, code, or documentation

    • 💩 :hankey: please avoid needing to use as it's for when moving files or content between branches

    • 💫 :dizzy: when re-naming or moving files within a branch, it'll happen for newer projects but need for use is to be avoided past version 0.0.5

    • 🐛 :bug: for stomping bugs in general

    • 🚬 :smoking: for resource bug fixes, eg. memory leaks, recursion limits, CPU load

    • 👊 :facepunch: when blaming one's self and new commit is to fix bug from recently past commit

    • 🚯 :do_not_litter: when blaming another's recent changes for requiring new committed bug fix

    • 🔒 :lock: for security related fixes

    • 🐧 :penguin: for fixing or improving Linux performance or compatibility

    • 🍎 :apple: for fixing or improving Apple/Mac performance or compatibility

    • 🏁 :checkered_flag: for fixing or improving Windows/MS performance or compatibility

    • ⬆️ :arrow_up: for tracking upgraded dependencies

    • ⬇️ :arrow_down: for tracking downgraded dependencies

    • 🔖 :bookmark: for Tagging Releases and Request For Comments (RFC)

    • ✅ :white_check_mark: for adding tests

    • 💚 :green_heart: when fixing Continuous Integration builds

    • 🌠 :stars: for accepting a Pull Request

    • ⛔ :no_entry: for rejecting a Pull Request

  • Additional notes should follow Markdown Style Guidelines; except for headings as #s are considered comments by default and thus ignored by many commit message handlers, see following example for other formatting differences

git add README.md
git commit -F- <<'EOF'
:memo: Added more content to readme file and spell-checked documentation



**Additions**
Links where tested locally and new content should explain things better.


**Corrections**
Other than spelling there where a few confusing spots that where also reworded.
EOF

Git Branch Tips

This Organization encourages the use of orphan branches for separating Code to be included in other projects from Documentation and Usage Examples. Non-orphaned development branches are encouraged when adding features or fixing bugs.

master branch may only contain;

  • lib or shared-functions directory, should only be used for files that directly support the script-name.sh file, otherwise please split out reusable code to separate repositories for including as submodules within the gh-pages branch

  • .git/ directory, required for version tracking and logging changes

  • readme.md file, should be a quick start documenting installation and/or usage

  • script-name.sh file, any dependencies should be listed within the .gitmodules file under the gh-pages branch

gh-pages branch (sometimes example branch) may contain;

  • modules directory, that contains a submodule subdirectory tracking the master branch, eg. modules/git-shell-commands

  • .gitmodules file, used by Git to version track submodules

  • .travis.yml file, used by Travis CI for public automated tests of code

  • README.md file, should be a quick start on development setup for fixing bugs or adding features via Pull Requests

  • example_usage.sh file, should demonstrate how code from the master branch is intended to be used

Development Git Branches

Development branches are excellent for privately tracking series of changes for new features or especially pervasive bugs. Merging with a squash commit back to one of the main line branches prior to publicly pushing to a fork is encouraged, however, please try to be targeted as to what each committed change pertains to.

Example dev-master branch initialization

cd "${HOME}/github/${_organization}/new-project"


git checkout master
git checkout -b dev-master

Commit changes to dev-master, then after tests have passed preform a squash merge of dev-master from the master branch

git checkout master
git merge --strategy-option theirs --squash dev-master

git commit -F- <<'EOF'
:bug: Fixes volume not being set to _`11`_ for solos



**Edits**
`cow_bell.sh` file, sets volume to max when `cow_bell()` solo starts
EOF


git push forked master

Git Merge Tips

Never git merge master from the gh-pages branch, and definitely do not git merge gh-pages when the master branch is checked out; orphaned branches should only be merged to and from their respective development (dev-) prefixed branches.

Squash merging is preferred for targeted edits, eg...

git checkout master
git merge --strategy-option theirs --squash dev-master


git commit -F- <<'EOF'
:shell: Asking permission from checkboxes before modifying state



**Changes**
`new-script.js` file, `uncheck_all()` continues on unchecked boxes and `check_all()` continues on checked boxes
EOF


git push forked master

Also be wary of rm vs git rm and mv vs git mv commands, when merging from a development branch back to one of the mainline branches the non-git wrapped commands will not update state between branches, and Pull Requests that confuse version management will be rejected.

Pull Requests

Issuing Pull Requests to repositories maintained by this Organization will only be considered if shared under the same licensing defined under License section of this document. Please use any relevant examples from the pull_request.md Template and adherer to the Style Guidelines for Git Commits

License

By default all Code (including Documentation) are shared under version three (3) of the GNU AGPL license.

Contributing Guidelines for Git Utilities
Copyright (C) 2019  S0AndS0

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation; version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Attribution

Portions of this document, such as emoji usage, where inspired by contributing.md guidelines from the Atom IDE development team.