Initial commit

.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,37 @@
+---
+name: Bug
+about: Report a bug
+labels: bug
+---
+
+<!--
+
+Please read the relevant sections in CONTRIBUTING.md before creating a bug report.
+
+-->
+
+<!-- Uncomment the next line if applicable. -->
+<!-- > **Note:** I would like to create a pull request for this bug. -->
+
+### Reproduction Steps
+
+<!-- Describe the exact steps that reproduce the bug. -->
+
+### Expected Behavior
+
+<!-- Describe the correct behavior you expect to see. -->
+
+### Actual Behavior
+
+<!-- Describe the behavior you see after executing the reproduction steps. -->
+
+### Additional Information
+
+<!--
+
+- Mention whether the bug started appearing after an update, and if it did, which version you were updating from.
+- Describe the environment (operating system and other relevant software) in which the bug occurred.
+- Share relevant screenshots or animated GIFs.
+- Share anything else you consider important.
+
+-->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/enhancement.md

@@ -0,0 +1,35 @@
+---
+name: Enhancement
+about: Suggest an enhancement
+labels: enhancement
+---
+
+<!--
+
+Please read the relevant sections in CONTRIBUTING.md before creating an enhancement suggestion.
+
+-->
+
+<!-- Uncomment the next line if applicable. -->
+<!-- > **Note:** I would like to create a pull request for this enhancement. -->
+
+### Description
+
+<!-- Describe the changes that the enhancement introduces. -->
+
+### Why?
+
+<!-- Describe the problems that the enhancement solves. -->
+
+### Alternatives
+
+<!-- Describe any alternatives you have considered and why they are not satisfactory. -->
+
+### Additional Information
+
+<!--
+
+- Share relevant screenshots or animated GIFs.
+- Share anything else you consider important.
+
+-->

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,5 @@
+---
+name: Question
+about: Ask a question
+labels: question
+---

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+<!--
+
+Please read the relevant sections in CONTRIBUTING.md before creating a pull request.
+
+-->
+
+### Issue
+
+<!-- Link to the GitHub issue that this pull request closes. -->
+
+### Drawbacks
+
+<!-- Describe possible side-effects or negative impacts of the code change. -->
+
+### Tests
+
+<!-- Describe the steps you took to verify that the code works as expected and does not introduce regressions. -->

.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: Release
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+jobs:
+  GitHub:
+    runs-on: ubuntu-22.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v3.0.2
+      - run: >
+          curl
+          --fail
+          --no-progress-meter
+          --request POST
+          --header "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}"
+          --header "Accept: application/vnd.github.v3+json"
+          --data-raw '{"tag_name":"${{ github.ref_name }}","body":"Check the [changelog](CHANGELOG.md) for more details."}'
+          https://api.github.com/repos/${{ github.repository }}/releases

.github/workflows/sqm.yml

@@ -0,0 +1,11 @@
+name: Software Quality Management
+on: [pull_request, push]
+jobs:
+  Testing:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v3.0.2
+      - run: sbin/provision
+      - run: sbin/format -c
+      - run: sbin/lint
+      - run: sbin/test

.gitignore

@@ -0,0 +1 @@
+.vagrant/

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/TobyGiacometti/test.sh/compare/1.0.0...HEAD

CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at <https://www.tobygiacometti.com/contact/>. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the project community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,168 @@
+# Contribution Guide
+
+First of all, thanks for your interest and for taking the time to contribute! This document shall be your guide throughout the contribution process and will hopefully answer any questions you have.
+
+## Table of Contents
+
+- [Response Times](#response-times)
+- [Reporting Bugs](#reporting-bugs)
+- [Suggesting Enhancements](#suggesting-enhancements)
+- [Contributing Changes](#contributing-changes)
+    - [Prerequisites](#prerequisites)
+    - [Development Environment](#development-environment)
+    - [Conventions](#conventions)
+        - [General](#general)
+        - [Unix Shell Script](#unix-shell-script)
+    - [Testing](#testing)
+    - [Pull Request](#pull-request)
+- [Code of Conduct](#code-of-conduct)
+- [Questions](#questions)
+
+## Response Times
+
+This project has been made available to you without expecting anything in return. As a result, maintenance does not happen on a set schedule. Please keep in mind that the irregular maintenance schedule can lead to significant delays in response times.
+
+## Reporting Bugs
+
+Before reporting a bug, please check if the bug occurs in the latest version. If it does, and if it hasn't already been reported in the [bug tracker][1], feel free to [file a bug report][2].
+
+## Suggesting Enhancements
+
+> **Note:** Simplicity is a core principle of this project. Every enhancement suggestion is carefully evaluated and only accepted if the usefulness of the enhancement greatly outweighs any increase in complexity.
+
+Before suggesting an enhancement, please ensure that the enhancement is not implemented in the latest version. In addition, please ensure that there is no straightforward alternative to achieve the desired outcome. If these conditions are met, and if the enhancement hasn't already been suggested in the [enhancement tracker][3], feel free to [file an enhancement suggestion][4].
+
+## Contributing Changes
+
+### Prerequisites
+
+Before making changes that you plan to contribute, please follow these instructions:
+
+- **Changes related to a [reported bug][1]:** Make sure that the bug has not yet been assigned to anybody (and that nobody has volunteered) and write a comment letting the community know that you have decided to fix the bug.
+- **Changes related to an unreported bug:** [File a bug report][2].
+- **Changes related to an [already suggested enhancement][3]:** Make sure that the enhancement has not yet been assigned to anybody and write a comment letting the maintainers know that you would like to implement the enhancement. Wait until the enhancement suggestion has been assigned to you.
+- **Changes related to a not yet suggested enhancement:** [File an enhancement suggestion][4] and wait until it has been assigned to you.
+
+Following these instructions keeps you (and others) from investing time in changes that would get rejected or are already being worked on.
+
+### Development Environment
+
+This project uses [Vagrant][5] to manage a portable development environment. Simply execute `vagrant up` inside the project's directory to start the setup. Once completed, you can access the development environment with `vagrant ssh`.
+
+### Conventions
+
+#### General
+
+- Code *should* document itself (meaningful naming).
+- Code *must* be formatted by executing `vagrant ssh -c /mnt/project/sbin/format` inside the project's directory.
+
+#### Unix Shell Script
+
+- The [general conventions][6] *must* be followed.
+- Lines longer than 80 characters *should* be avoided.
+- Unless the script is inside the `sbin` or `t` directories, it *must* have following file header:
+
+    ```sh
+    # shellcheck shell=sh
+
+    # test.sh
+    # https://github.com/TobyGiacometti/test.sh
+    # Copyright (c) <year> Toby Giacometti and contributors
+    # Apache License 2.0
+    ```
+
+    The file header *must* be separated from other elements with an empty line.
+
+- Commands *must* be grouped and ordered as follows and groups *must* be separated from each other with an empty line:
+    1. Environment checks (check if OS is supported, etc.)
+    2. Shell option setting/unsetting
+    3. File sourcing
+    4. Public function definitions
+    5. Internal function definitions
+    6. Trap registrations
+    7. Common public variable assignments
+    8. Common internal variable assignments
+    9. Main logic
+- Functions *must* be separated from each other with an empty line.
+- Function and variable names *must* use snake case.
+- If the script is to be sourced by end users, functions and variables that are not intended for public use *must* be named with the `_testsh_` prefix.
+- Names of functions that make modifications *must* read as imperative verb phrases. For example: `print_help`, `fork`.
+- Names of functions that don't make modifications *must* read as [predicate phrases][7]. For example: `is_empty`, `exists`.
+- Functions *must* be documented using Markdown syntax and following template:
+
+    ```sh
+    #---
+    # Summary for function (if not obvious or description is provided).
+    #
+    # Description for function (if extended documentation is needed).
+    #
+    # @param $@ Description for all parameters (if function takes multiple arguments that are all of the same type).
+    # @param $<number> Description for a parameter (if not using a description for all parameters).
+    # @param... Description for remaining parameters (if function takes multiple trailing arguments that are all of the same type).
+    # @stdin Description for STDIN (if used).
+    # @stdout Description for STDOUT (if used).
+    # @stderr Description for STDERR (if used for non-error output).
+    # @fd <number> Description for a non-standard file descriptor.
+    # @status Description for all status codes (if documenting each status code separately is suboptimal).
+    # @status <number> Description for a non-standard status code (if not using a description for all status codes).
+    # @exit (if function calls `exit` outside of error cases)
+    # @internal (if function is not intended for public use)
+    func() { :; }
+    ```
+
+- If the script is to be sourced by end users, global variables *must* be documented using Markdown syntax and following template:
+
+    ```sh
+    #---
+    # @var Description for variable (if not obvious).
+    # @internal (if variable is not intended for public use)
+    var=
+    #---
+    # @var $var_<placeholder>
+    #      <placeholder> Description for placeholder.
+    #      Description for dynamically defined variable (if not obvious).
+    # @readonly (if variable is read-only)
+    # @internal (if variable is not intended for public use)
+    ```
+
+### Testing
+
+The tests are stored inside the `t` directory. Simply execute `vagrant ssh -c /mnt/project/sbin/test` inside the project's directory to run the test suite.
+
+### Pull Request
+
+Before creating a pull request, please follow these instructions:
+
+- Recreate the development environment if `sbin/provision` has been modified.
+- Ensure that the instructions in the [Prerequisites][8] and [Conventions][9] sections have been followed.
+- Lint the codebase by executing `vagrant ssh -c /mnt/project/sbin/lint` inside the project's directory.
+- Update the [test suite][10] and exercise the code you have written.
+- Update the [README file][11].
+- Update the [changelog][12].
+
+After the pull request has been created, confirm that all [status checks][13] are passing. If you believe that a status check failure is a false positive, comment on the pull request and a maintainer will review the failure.
+
+## Code of Conduct
+
+Please note that this project is released with a [contributer code of conduct][14]. By participating in this project you agree to abide by its terms.
+
+## Questions
+
+Still have questions? No problem! Use the [question tracker][15] to [ask a question][16].
+
+[1]: https://github.com/TobyGiacometti/test.sh/issues?q=is%3Aissue+label%3Abug
+[2]: https://github.com/TobyGiacometti/test.sh/issues/new?template=bug.md
+[3]: https://github.com/TobyGiacometti/test.sh/issues?q=is%3Aissue+label%3Aenhancement
+[4]: https://github.com/TobyGiacometti/test.sh/issues/new?template=enhancement.md
+[5]: https://www.vagrantup.com
+[6]: #general
+[7]: https://en.wikipedia.org/wiki/Predicate_(grammar)
+[8]: #prerequisites
+[9]: #conventions
+[10]: #testing
+[11]: README.md
+[12]: CHANGELOG.md
+[13]: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks
+[14]: CODE_OF_CONDUCT.md
+[15]: https://github.com/TobyGiacometti/test.sh/issues?q=is%3Aissue+label%3Aquestion
+[16]: https://github.com/TobyGiacometti/test.sh/issues/new?template=question.md