fix(docs): comprehensive overhaul to meet guidelines

open-turo · Apr 27, 2022 · 07dc27b · 07dc27b
1 parent fcccfb0
commit 07dc27b
Show file tree

Hide file tree

Showing 7 changed files with 117 additions and 56 deletions.
diff --git a/README.md b/README.md
@@ -1,3 +1,31 @@
-# actions-jvm
+# `open-turo/actions-jvm`
 
-GitHub Actions for JVM, Java, and Kotlin repositories
+GitHub Actions for JVM based repositories, such as for Java and Kotlin.
+
+## 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 that runs lint on a JVM (e.g. Java) based GitHub repository.
+## Description
+
+GitHub Action to lint a JVM based repository
 
 ## Usage
 
@@ -12,7 +14,16 @@ jobs:
         uses: open-turo/actions-jvm/lint@v1
 ```
 
-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`   |         |
+
+## Runs
+
+This action is an `composite` action.
 
 ## Lint Checks
 
@@ -23,9 +34,5 @@ This action runs the following lint checks:
 
 ## Notes
 
-- If the 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.yml` 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.
+- 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).
diff --git a/lint/action.yaml b/lint/action.yaml
@@ -1,13 +1,13 @@
-name: "jvm Lint"
-description: "Lints jvm repository"
+name: jvm Lint
+description: GitHub Action to lint a JVM based repository
 inputs:
   checkout-repo:
     required: false
-    description: "Perform checkout as first step of action"
+    description: Perform checkout as first step of action
     default: "true"
   github-token:
     required: true
-    description: "GitHub token that can checkout the repository. e.g. 'secrets.GITHUB_TOKEN'"
+    description: GitHub token that can checkout the repository. e.g. 'secrets.GITHUB_TOKEN'
 runs:
   using: composite
   steps:

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 to publish 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:
@@ -23,44 +23,54 @@ 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`   |         |
+| 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`  |         |
 
-### Inputs
+## Outputs
 
-| Input Parameter | Required | Description                                                                                                           |
-| :-------------: | :------: | --------------------------------------------------------------------------------------------------------------------- |
-|  checkout-repo  |  false   | Whether or not to checkout the repo as the first step                                                                 |
-|  github-token   |   true   | GitHub token that can checkout the repository as well as create tags/releases against it. e.g. 'secrets.GITHUB_TOKEN' |
-|   go-version    |  false   | The version of golang that is needed                                                                                  |
+| 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    |
 
-### Outputs
+## Runs
 
-|     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). |
+This action is an `composite` action.
 
-#### Using Output Variables:
+## Additional Examples
+
+### using output parameters example
 
 ```yaml
 jobs:
   build:
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           fetch-depth: 0
-      - name: Semantic release
+      - name: Release
         uses: open-turo/actions-jvm/release@v1
         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,38 +1,39 @@
-name: "GitHub Action Release & Publish"
-description: "Publish a new release of the Action - adds a new major tag"
+name: GitHub Action Release and Publish
+description: GitHub Action to publish a new release
 inputs:
   checkout-repo:
     required: false
-    description: "Perform checkout as first step of action"
+    description: Perform checkout as first step of action
     default: "true"
   github-token:
     required: true
-    description: "GitHub token that can checkout the repository as well as create tags/releases against it. e.g. 'secrets.GITHUB_TOKEN'"
+    description: GitHub token that can checkout the repository as well as create tags/releases against it. e.g. 'secrets.GITHUB_TOKEN'
   dry-run:
     required: false
-    description: "Whether to run semantic release in `dry-run` mode. It will override the dryRun attribute in your configuration file"
+    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."
+    description: Extra plugins for pre-install. You can also specify specifying version range for the extra plugins if you prefer.
 outputs:
   new-release-published:
-    description: "Whether a new release was published"
+    description: Whether a new release was published
     value: ${{ steps.release.outputs.new_release_published }}
   new-release-version:
-    description: "Version of the new release"
+    description: Version of the new release
     value: ${{ steps.release.outputs.new_release_version }}
   new-release-major-version:
-    description: "Major version of the new release"
+    description: Major version of the new release
     value: ${{ steps.release.outputs.release-major }}
 runs:
   using: composite
   steps:
-    - uses: actions/checkout@v3
+    - name: Checkout
+      uses: actions/checkout@v3
       if: inputs.checkout-repo
       with:
         fetch-depth: 0
-    - name: Semantic Release
-      id: release
+    - name: Release
       uses: cycjimmy/semantic-release-action@v2
       with:
         dry_run: ${{ inputs.dry-run }}

diff --git a/test/README.md b/test/README.md
@@ -1,5 +1,7 @@
 # GitHub Action Test
 
+## Description
+
 GitHub Action that runs unit tests present within a JVM based (e.g. Java) GitHub repository and report test coverage metrics.
 
 ## Usage
@@ -12,7 +14,18 @@ jobs:
         uses: open-turo/actions-jvm/test@v1
 ```
 
-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`   |         |
+| artifactory-username   | Username to use for Artifactory access                                     | `true`   |         |
+| artifactory-auth-token | Authentication token to use with username for Artifactory access           | `true`   |         |
+
+## Runs
+
+This action is an `composite` action.
 
 ## Test
 
@@ -22,3 +35,7 @@ repository and all subdirectories.
 ```shell
 gradelw test -PartifactoryUsername=?? -PartifactoryAuthToken=??
 ```
+
+## Notes
+
+- By default, this action will perform actions/checkout as its first step.
diff --git a/test/action.yaml b/test/action.yaml
@@ -1,27 +1,25 @@
-name: "jvm Test"
-description: "Executes jvm unit tests within repository reporting test coverage metrics"
+name: jvm Test
+description: GitHub Action that runs unit tests present within a JVM based (e.g. Java) GitHub repository and report test coverage metrics.
 inputs:
   checkout-repo:
     required: false
     description: "Perform checkout as first step of action"
     default: "true"
   github-token:
     required: true
-    description: "GitHub token that can checkout the repository. e.g. 'secrets.GITHUB_TOKEN'"
+    description: GitHub token that can checkout the repository. e.g. 'secrets.GITHUB_TOKEN'
   artifactory-username:
     required: true
-    description: "Username to use for Artifactory access"
+    description: Username to use for Artifactory access
   artifactory-auth-token:
     required: true
-    description: "Authentication token to use with username for Artifactory access"
+    description: Authentication token to use with username for Artifactory access
 runs:
   using: composite
   steps:
     - name: Checkout
       uses: actions/checkout@v3
       if: inputs.checkout-repo
-      with:
-        fetch-depth: 0
     - name: Sdkman
       shell: bash
       run: sdk env install