fix(docs): comprehensive overhaul to meet guidelines

open-turo · Apr 27, 2022 · 1a8c10b · 1a8c10b
1 parent 5ef880e
commit 1a8c10b
Show file tree

Hide file tree

Showing 9 changed files with 124 additions and 88 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,6 @@
-# actions-gha
+# `open-turo/actions-gha`
+
+GitHub Actions for GitHub Action repositories
 
 [![GitHub release](https://img.shields.io/github/release/Naereen/StrapDown.js.svg)](https://GitHub.com/Naereen/StrapDown.js/releases/)
 [![Release date][release-date-image]][release-url]
@@ -8,57 +10,47 @@
 [![semantic-release][semantic-image]][semantic-url]
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
 
-GitHub Actions for GitHub Action repositories
-
 ## Actions
 
 ### action: [`lint`](./lint)
 
-```yaml
-jobs:
-  build:
-    steps:
-      - name: Lint
-        uses: open-turo/actions-gha/lint@v1
-          ## example value for github-token provided below
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-```
+Lint will run pre-commit linters against the consumer repository, optionally checking out, optionally running `npm ci`, install [actionlint](rhysd/actionlint), run [action-pre-commit](https://github.com/open-turo/action-pre-commit), and lastly optionally run [check-build](./check-build/README.md).
+
+See usage [here](./lint/README.md#usage).
+
+Documentation is found [here](./lint/README.md).
 
 ### action: [`check-build`](./check-build)
 
-```yaml
-jobs:
-  build:
-    steps:
-      - name: Check build
-        uses: open-turo/actions-gha/check-build@v1
-          ## example value for github-token provided below
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-```
+Checks to see if there are any changes in the consumer repository by running `npm run prepare` and determining if differences exist in the generated `dist` directory.
+
+See usage [here](./check-build/README.md#usage).
+
+Documentation is found [here](./check-build/README.md).
 
 ### action: [`release`](./release)
 
-```yaml
-jobs:
-  build:
-    steps:
-      - name: Release
-        uses: open-turo/actions-gha/release@v1
-        with:
-          dry_run: true
-```
+Release will optionally checkout the consumer repository and attempt a [Semantic Release](https://semantic-release.gitbook.io/semantic-release/usage/configuration) using the root level configuration file (e.g. `.releaserc.json`) indicating branches and plugins to use to facilitate the release. If a new release is published, a major version will also be released.
+
+See usage [here](./release/README.md#usage).
+
+Documentation is found [here](./release/README.md).
 
 ### action: [`test`](./test)
 
-```yaml
-jobs:
-  test:
-    steps:
-      - name: Test
-        uses: open-turo/actions-gha/test@v1
-          ## example value for github-token provided below
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-```
+Optionally checks out the GitHub consumer repository, and if a `package-lock.json` file is found at the root level directory, runs `npm ci`, `npm test`, and [coveralls](https://github.com/coverallsapp/github-action).
+
+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.
 
 <!-- Links: -->
 

diff --git a/check-build/README.md b/check-build/README.md
@@ -1,6 +1,8 @@
 # GitHub Action Check Node Build
 
-GitHub Action runs checks to see if the code has changed without running a build.
+## Description
+
+GitHub Action that determines if the code has changed without actually running a build.
 
 ## Usage
 
@@ -15,6 +17,16 @@ jobs:
           github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
+## Inputs
+
+| parameter    | description                                                               | required | default |
+| ------------ | ------------------------------------------------------------------------- | -------- | ------- |
+| github-token | GitHub token that can create/delete comments. e.g. 'secrets.GITHUB_TOKEN' | `true`   |         |
+
+## Runs
+
+This action is an `composite` action.
+
 ## Dist check
 
 Runs `npm run prepare` and checks to see if there are uncommitted changes.
diff --git a/check-build/action.yaml b/check-build/action.yaml
@@ -1,5 +1,5 @@
 name: Check node build
-description: Checks whether node has been built and committed into the ./dist directory
+description: GitHub Action that determines if the code has changed without actually running a build.
 inputs:
   github-token:
     required: true

diff --git a/lint/README.md b/lint/README.md
@@ -1,6 +1,8 @@
 # GitHub Action Lint
 
-GitHub Action runs lint on a GitHub Action
+## Description
+
+GitHub Action that runs lint on a GitHub Action
 
 ## Usage
 
@@ -14,20 +16,28 @@ 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 create/delete comments. Usually - 'secrets.GITHUB_TOKEN' | `true`   |         |
+
+## Runs
+
+This action is an `composite` action.
 
 ## Lint Checks
 
 This action runs the following lint checks:
 
 - [action-pre-commit](https://github.com/open-turo/action-pre-commit)
-- [check-build](../check-build) - if the action is `node`, this checks that build has been run and committed.
+- [check-build](../check-build/README.md) - if the action is `node`, this checks that build has been run and committed.
 
 ## Notes
 
-- If the repository has a `package-lock.json`
+- By default, this action will perform actions/checkout as its first step.
+- If the consumer repository has a `package-lock.json`
   - It will execute `npm ci` before running the `pre-commit` step.
   - It will run the `check-build` action.
-- `actionlint` will be installed and in the path to ensure that https://github.com/rhysd/actionlint can be run directly.
-- 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.
+- This expects that `.commitlintrc.yaml` will be present at the root level of the consumer repository to enforce [`conventional-commit`](https://github.com/wagoid/commitlint-github-action).
diff --git a/lint/action.yaml b/lint/action.yaml
@@ -1,5 +1,5 @@
 name: GitHub Action Lint
-description: Lints GitHub Actions
+description: GitHub Action that runs lint on a GitHub Action
 inputs:
   checkout-repo:
     required: false
@@ -12,7 +12,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 produces a new Release of an Action - adds a new major tag
 
-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.
+### Step1: Set any [Semantic Release Configuration](https://github.com/semantic-release/semantic-release/blob/master/docs/usage/configuration.md#configuration) in the consumer 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.
+### Step2: [Add Secrets](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) in the consumer 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.
+### Step3: Add a [Workflow File](https://help.github.com/en/articles/workflow-syntax-for-github-actions) to the consumer repository to create custom automated processes.
 
-#### Basic Usage:
+## Usage
 
 ```yaml
 steps:
@@ -23,22 +23,36 @@ 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    |
+| dry-run       | Whether to run semantic release in `dry-run` mode. It will override the `dryRun` attribute in your configuration file | `false`  |         |
+| extra-plugins | Extra plugins for pre-install. You can also specify specifying version range for the extra plugins if you prefer.     | `false`  |         |
+| github-token  | GitHub token that can create/delete comments. e.g. 'secrets.GITHUB_TOKEN'                                             | `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                                                              |
-| :-------------: | :------: | ------------------------------------------------------------------------ |
-|     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:
 
@@ -65,9 +79,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:
@@ -79,16 +91,7 @@ jobs:
           dry-run: true
 ```
 
-### 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:
@@ -103,3 +106,7 @@ jobs:
           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 produces a new Release of an Action - adds a new major tag
 inputs:
   checkout-repo:
     required: false
@@ -18,8 +18,7 @@ inputs:
   github-token:
     required: false
     description: >-
-      GitHub token that can create/delete comments. Usually -
-      'secrets.GITHUB_TOKEN'
+      GitHub token that can create/delete comments. e.g.  'secrets.GITHUB_TOKEN'
 outputs:
   new-release-published:
     description: Whether a new release was published

diff --git a/test/README.md b/test/README.md
@@ -1,6 +1,8 @@
 # GitHub Action Test
 
-GitHub Action runs tests within the consuming GitHub repository.
+## Description
+
+GitHub Action that conditionally uses Node.js to test a GitHub Action
 
 ## Usage
 
@@ -14,7 +16,16 @@ 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 passed to coveralls. Usually - 'secrets.GITHUB_TOKEN'. Coveralls uses this token to verify the posted coverage data on the consumer repo and create a new check based on the results. It is built into Github Actions and does not need to be manually specified in your secrets store. | `true`   |         |
+
+## Runs
+
+This action is an `composite` action.
 
 ## Test
 
@@ -23,4 +34,9 @@ For node based actions, it will run:
 ```shell
 npm ci
 npm test -- --coverage
+coveralls
 ```
+
+## Notes
+
+- By default, this action will perform actions/checkout as its first step.
diff --git a/test/action.yaml b/test/action.yaml
@@ -1,18 +1,18 @@
 name: GitHub Action Test
-description: Tests GitHub Actions
+description: GitHub Action that conditionally uses Node.js to test a GitHub Action
 inputs:
   checkout-repo:
     required: false
     description: Perform checkout as first step of action
     default: "true"
   github-token:
     required: true
-    description: GitHub token passed to coveralls. Usually - 'secrets.GITHUB_TOKEN'. Coveralls uses this token to verify the posted coverage data on the repo and create a new check based on the results. It is built into Github Actions and does not need to be manually specified in your secrets store.
+    description: GitHub token passed to coveralls. Usually - 'secrets.GITHUB_TOKEN'. Coveralls uses this token to verify the posted coverage data on the consumer repo and create a new check based on the results. It is built into Github Actions and does not need to be manually specified in your secrets store.
 runs:
   using: composite
   steps:
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       if: inputs.checkout-repo
     - name: Test node
       if: hashFiles('package-lock.json') != ''