fix(docs): comprehensive overhaul to meet guidelines

open-turo · Apr 29, 2022 · 0e0ab7b · 0e0ab7b
1 parent 2e6d6bb
commit 0e0ab7b
Show file tree

Hide file tree

Showing 7 changed files with 108 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,31 @@
-# actions-node
+# `open-turo/actions-node`
 
-GitHub Actions for Node.js, Javascript, and Typescript repositories
+GitHub Actions for Node.js, JavaScript, and TypeScript based repositories
+
+## Actions
+
+### action: [`lint`](./lint)
+
+See usage [here](./lint/README.md#usage).
+
+Documentation is found [here](./lint/README.md).
+
+### action: [`release`](./release)
+
+See usage [here](./release/README.md#usage).
+
+Documentation is found [here](./release/README.md).
+
+### action: [`test`](./test)
+
+See usage [here](./test/README.md#usage).
+
+Documentation is found [here](./test/README.md).
+
+## Get Help
+
+Each Action has a detailed README for how to use it as referenced above. Please review Issues, post new Issues against this repository as needed.
+
+## Contributions
+
+Please see [here](https://github.com/open-turo/contributions) for guidelines on how to contribute to this project.
diff --git a/lint/README.md b/lint/README.md
@@ -1,6 +1,8 @@
 # GitHub Action Lint
 
-GitHub Action runs lint on a node based GitHub repository
+## Description
+
+GitHub Action that lints a Node based repository
 
 ## Usage
 
@@ -15,7 +17,17 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-Note: by default, this action will perform actions/checkout as its first step.
+## Inputs
+
+| parameter     | description                                                                | required | default |
+| ------------- | -------------------------------------------------------------------------- | -------- | ------- |
+| checkout-repo | Perform checkout as first step of action                                   | `false`  | true    |
+| github-token  | GitHub token that can checkout the repository. e.g. 'secrets.GITHUB_TOKEN' | `true`   |         |
+| node-version  | The version of Node.js to setup and use with Yarn                          | `true`   | 16      |
+
+## Runs
+
+This action is an `composite` action.
 
 ## Lint Checks
 
@@ -25,5 +37,5 @@ This action runs the following lint checks:
 
 ## Notes
 
+- By default, this action will perform actions/checkout as its first step.
 - This expects that `.commitlintrc.yaml` will be present to enforce [`conventional-commit`](https://github.com/wagoid/commitlint-github-action).
-- Checkout must have history to ensure that commit message linting works.
diff --git a/lint/action.yaml b/lint/action.yaml
@@ -1,5 +1,5 @@
 name: node Lint
-description: Lints node based repository
+description: GitHub Action that lints a Node based repository
 inputs:
   checkout-repo:
     required: false
@@ -16,7 +16,7 @@ runs:
   using: composite
   steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       if: inputs.checkout-repo
       with:
         fetch-depth: 0

diff --git a/release/README.md b/release/README.md
@@ -1,18 +1,18 @@
 # GitHub Action Release
 
-GitHub Action for [Semantic Release][semantic-url].
+## Description
 
-## Usage
+GitHub Action that publishes a new release.
 
-Note: by default, this action will perform actions/checkout as its first step.
+## Configuration
 
 ### Step1: Set any [Semantic Release Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in your repository.
 
 ### Step2: [Add Secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) in your repository for the [Semantic Release Authentication](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/ci-configuration.md#authentication) Environment Variables.
 
 ### Step3: Add a [Workflow File](https://help.github.com/en/articles/workflow-syntax-for-github-actions) to your repository to create custom automated processes.
 
-#### Basic Usage:
+## Usage
 
 ```yaml
 steps:
@@ -26,26 +26,38 @@ steps:
 ```
 
 **IMPORTANT**: `GITHUB_TOKEN` does not have the required permissions to operate on protected branches.
-If you are using this action for protected branches, replace `GITHUB_TOKEN` with [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). If using the `@semantic-release/git` plugin for protected branches, avoid persisting credentials as part of `actions/checkout@v2` by setting the parameter `persist-credentials: false`. This credential does not have the required permission to operate on protected branches.
+If you are using this action for protected branches, replace `GITHUB_TOKEN` with [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). If using the `@semantic-release/git` plugin for protected branches, avoid persisting credentials as part of `actions/checkout@v3` by setting the parameter `persist-credentials: false`. This credential does not have the required permission to operate on protected branches.
+
+## Inputs
+
+| parameter                  | description                                                                                                           | required | default |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
+| checkout-repo              | Perform checkout as first step of action                                                                              | `false`  | true    |
+| github-token               | GitHub token that can checkout the repository as well as create tags/releases against it. e.g. 'secrets.GITHUB_TOKEN' | `true`   |         |
+| node-version               | The version of Node.js to setup and use with Yarn                                                                     | `true`   | 16      |
+| artifactory-npm-auth-token | The Node Package Manager (npm) authentication token recognized by Artifactory                                         | `true`   |         |
+| dry-run                    | Whether to run semantic release in `dry-run` mode. It will override the `dryRun` attribute in your configuration file | `false`  | `false` |
+| extra-plugins              | Extra plugins for pre-install. You can also specify specifying version range for the extra plugins if you prefer.     | `false`  |         |
+
+## Outputs
+
+| parameter                 | description                         |
+| ------------------------- | ----------------------------------- |
+| new-release-published     | Whether a new release was published |
+| new-release-version       | Version of the new release          |
+| new-release-major-version | Major version of the new release    |
 
-### Inputs
+## Runs
 
-|      Input Parameter       | Required | Description                                                                                                            |
-| :------------------------: | :------: | ---------------------------------------------------------------------------------------------------------------------- |
-|       checkout-repo        |  false   | Whether to perform repository checkout as first step or not                                                            |
-|        github-token        |   true   | GitHub token that can checkout the repository as well as create tags/releases against it. e.g. 'secrets.GITHUB_TOKEN'" |
-|        node-version        |   true   | The version of Node.js to setup and use with Yarn                                                                      |
-| artifactory-npm-auth-token |   true   | The Node Package Manager (npm) authentication token recognized by Artifactory                                          |
-|          dry-run           |  false   | Whether to run semantic release in `dry-run` mode. [[Details](#dry_run)]                                               |
-|       extra-plugins        |  false   | Extra plugins for pre-install. [[Details](#extra_plugins)]                                                             |
+This action is an `composite` action.
 
-#### extra-plugins
+## Additional Examples
 
-> {Optional Input Parameter} Extra plugins for pre-install.
+### extra-plugins example
 
-The action can be used with `extra_plugins` option to specify plugins which are not in the [default list of plugins of semantic release](https://semantic-release.gitbook.io/semantic-release/usage/plugins#default-plugins). When using this option, please make sure that these plugins are also mentioned in your [semantic release config's plugins](https://semantic-release.gitbook.io/semantic-release/usage/configuration#plugins) array.
+The Action can be used with `extra-plugins` option to specify plugins which are not in the [default list of plugins of semantic release](https://semantic-release.gitbook.io/semantic-release/usage/plugins#default-plugins). When using this option, please make sure that these plugins are also mentioned in your [semantic release config's plugins](https://semantic-release.gitbook.io/semantic-release/usage/configuration#plugins) array.
 
-For example, if you want to use `@semantic-release/git` and `@semantic-release/changelog` extra plugins, these must be added to `extra_plugins` in your actions file and `plugins` in your [release config file](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file) as shown bellow:
+For example, if you want to use `@semantic-release/git` and `@semantic-release/changelog` extra plugins, these must be added to `extra-plugins` in your actions file and `plugins` in your [release config file](https://semantic-release.gitbook.io/semantic-release/usage/configuration#configuration-file) as shown bellow:
 
 Github Action Workflow:
 
@@ -73,9 +85,7 @@ Release Config:
   ]
 ```
 
-#### dry-run
-
-> {Optional Input Parameter} Whether to run semantic release in `dry-run` mode.<br>It will override the dryRun attribute in your configuration file.
+### dry-run example
 
 ```yaml
 jobs:
@@ -88,29 +98,24 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-### Outputs
-
-|     Output Parameter      | Description                                                                                                                       |
-| :-----------------------: | --------------------------------------------------------------------------------------------------------------------------------- |
-|   new-release-published   | Whether a new release was published (`true` or `false`)                                                                           |
-|    new-release-version    | Version of the new release. (e.g. `1.3.0`)                                                                                        |
-| new-release-major-version | Major version of the new release. (e.g. `1`)                                                                                      |
-|    new-release-channel    | The distribution channel on which the last release was initially made available (undefined for the default distribution channel). |
-
-#### Using Output Variables:
+### using output parameters example
 
 ```yaml
 jobs:
   build:
     steps:
       - name: Release
         uses: open-turo/actions-node/release@v1
-        id: release # Need an `id` for output variables
+        id: semantic # Need an `id` for output variables
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
       - name: Do something when a new release published
-        if: steps.release.outputs.new-release-published == 'true'
+        if: steps.semantic.outputs.new-release-published == 'true'
         run: |
           echo ${{ steps.semantic.outputs.new-release-version }}
           echo ${{ steps.semantic.outputs.new-release-major-version }}
 ```
+
+## Notes
+
+- By default, this action will perform actions/checkout as its first step.
diff --git a/release/action.yaml b/release/action.yaml
@@ -1,5 +1,5 @@
 name: GitHub Action Release & Publish
-description: Publish a new release of the Action - adds a new major tag
+description: GitHub Action that publishes a new release.
 inputs:
   checkout-repo:
     required: false
@@ -18,6 +18,7 @@ inputs:
   dry-run:
     required: false
     description: Whether to run semantic release in `dry-run` mode. It will override the `dryRun` attribute in your configuration file
+    default: "false"
   extra-plugins:
     required: false
     description: Extra plugins for pre-install. You can also specify specifying version range for the extra plugins if you prefer.
@@ -35,7 +36,7 @@ runs:
   using: composite
   steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       if: inputs.checkout-repo
       with:
         fetch-depth: 0

diff --git a/test/README.md b/test/README.md
@@ -1,6 +1,8 @@
 # GitHub Action Test
 
-GitHub Action that runs tests present within a node based GitHub repository.
+## Description
+
+GitHub Action that tests a node based repository
 
 ## Usage
 
@@ -15,7 +17,17 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-Note: by default, this action will perform actions/checkout as its first step.
+## Inputs
+
+| parameter     | description                                                                | required | default |
+| ------------- | -------------------------------------------------------------------------- | -------- | ------- |
+| checkout-repo | Perform checkout as first step of action                                   | `false`  | true    |
+| github-token  | GitHub token that can checkout the repository. e.g. 'secrets.GITHUB_TOKEN' | `true`   |         |
+| node-version  | The version of Node.js to setup and use with Yarn                          | `true`   | 16      |
+
+## Runs
+
+This action is an `composite` action.
 
 ## Test
 
@@ -25,3 +37,7 @@ It will run:
 yarn --pure-lockfile
 yarn test --coverage
 ```
+
+## Notes
+
+- By default, this action will perform actions/checkout as its first step.
diff --git a/test/action.yaml b/test/action.yaml
@@ -1,5 +1,5 @@
 name: node Test
-description: Tests node based repository
+description: GitHub Action that tests a node based repository
 inputs:
   checkout-repo:
     required: false
@@ -16,7 +16,7 @@ runs:
   using: composite
   steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       if: inputs.checkout-repo
     - name: Setup node
       uses: actions/setup-node@v2