docs: add contributing guidelines (#442)

* docs: add contributing guidelines

* chore: add clarifying comment

* fix: broken paths

* docs: another small note

* Update CONTRIBUTING.md

Co-authored-by: Jon Ursenbach <[email protected]>

* chore: one more small change

Co-Authored-By: Jon Ursenbach <[email protected]>

Co-authored-by: Jon Ursenbach <[email protected]>
Co-authored-by: Jon Ursenbach <[email protected]>

.github/workflows/gh-action-simple.yml

@@ -0,0 +1,20 @@
+# This GitHub Action isn't actually used in our CI process,
+# it's just an example workflow that doesn't require any secure tokens
+# so we can run it in any environment (i.e. a local env using `act`)
+name: GitHub Action Simple Example
+
+on: workflow_dispatch
+
+jobs:
+  simple:
+    name: GitHub Action Auth-Less
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout GitHub Action
+        uses: actions/[email protected]
+
+      # This is a simple example that runs our `validate` command on a local file.
+      - name: Run `validate` command
+        uses: ./ # in actual production usage, this value should be 'readmeio/rdme@XX'
+        with:
+          rdme: validate __tests__/__fixtures__/ref-oas/petstore.json

CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing
+
+## Running Shell Commands Locally 🐚
+
+To run test commands from within the repository, simply run your commands from the root of the repository and use `./bin/rdme` instead of `rdme` so it properly points to the command executable, like so:
+
+```sh
+./bin/rdme validate __tests__/__fixtures__/ref-oas/petstore.json
+```
+
+## Running GitHub Actions Locally 🐳
+
+To run GitHub Actions locally, we'll be using [`act`](https://github.com/nektos/act) (make sure to read their [prerequisites list](https://github.com/nektos/act#necessary-prerequisites-for-running-act) and have that ready to go before installing `act`)!
+
+Unfortunately (as of this writing), the maintainer hasn't tagged a release that includes [PR #793](https://github.com/nektos/act/issues/793), which is required for running the composite action setup we have defined in [`action.yml`](action.yml). You'll need to install `act` with the `--HEAD` flag:
+
+```sh
+brew install act --HEAD
+```
+
+As of this writing, this is the version of `act` that is able to successfully run our workflows (i.e. the output of the `act --version` command):
+
+```sh
+# https://github.com/nektos/act/commit/9abc87b
+act version HEAD-9abc87b
+```
+
+Once you've installed `act`, it'll ask you what Docker image size you'd like. The standard Medium ones should work just fine. Here's what your `~/.actrc` file should look like:
+
+```
+-P ubuntu-latest=ghcr.io/catthehacker/ubuntu:act-latest
+-P ubuntu-20.04=ghcr.io/catthehacker/ubuntu:act-20.04
+-P ubuntu-18.04=ghcr.io/catthehacker/ubuntu:act-18.04
+```
+
+Once it's configured, you can use the `-l` flag to to view all the workflows:
+
+```sh
+act -l # all workflows with the default event (i.e. `push`)
+act workflow_dispatch -l # all workflows with the `workflow_dispatch` event
+```
+
+Running the latter command will return the following:
+
+```
+Stage  Job ID  Job name                 Workflow name                 Workflow file         Events
+0      simple  GitHub Action Auth-Less  GitHub Action Simple Example  gh-action-simple.yml  workflow_dispatch
+```
+
+And finally, you can use that Job ID to execute a workflow with the `-j` flag (make sure Docker is running!):
+
+```sh
+act -j simple
+```
+
+## Code Style Guidelines
+
+### Usage of `console`
+
+As you'll learn in our commands logic (see [`bin/rdme`](bin/rdme) and the [`src/cmds`](src/cmds) directory), we wrap our command outputs in resolved/rejected [`Promise` objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) and use [`bin/rdme`](bin/rdme) file to log the results to the console and return the correct status code. This is so we can write more resilient tests, ensure that the proper exit codes are being returned, and make debugging easier.
+
+When writing command logic, avoid using `console` statements (and correspondingly, avoid mocking `console` statements in tests) when possible.
+
+<img align="right" width="25%" style="margin-bottom: 2em" src="https://owlbert.io/images/owlberts-png/Waiter.psd.png">
+
+### Commit Conventions
+
+When pushing or merging PRs in to `main`, your commit messages should follow the [Angular commit conventions](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines). At it's simplest, this looks something like `{type}: change this, add that`, where the commit `{type}` can be one of the following:
+
+| Commit Type | Description                              |
+| :---------- | :--------------------------------------- |
+| `build`     | creating a new release                   |
+| `chore`     | assorted minor changes                   |
+| `ci`        | updates related to the ci process        |
+| `docs`      | documentation updates                    |
+| `feat`      | new elements; major features and updates |
+| `fix`       | bug fixes; security updates              |
+| `perf`      | performance improvements                 |
+| `refactor`  | general refactors                        |
+| `revert`    | reverting a previous commit              |
+| `style`     | aesthetic changes                        |
+| `test`      | adding or updating existing tests        |
+
+You can also optionally note the `{scope}` of your changes in an additional parenthetical. If your changes require a longer description, feel free to add a commit message with further details! Combining all of these together, you might end up with something like:
+
+```text
+feat(auth): add support for cookie auth
+
+- some more details
+- about the changes
+```