From a32ec3723607f99dd71c070eef9a057e3d276a7d Mon Sep 17 00:00:00 2001
From: Nick Alteen <ncalteen@github.com>
Date: Wed, 23 Aug 2023 13:40:40 -0400
Subject: [PATCH] Format and expand README

---
 README.md | 230 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 163 insertions(+), 67 deletions(-)

diff --git a/README.md b/README.md
index fac1dd6..dd575ce 100644
--- a/README.md
+++ b/README.md
@@ -1,105 +1,201 @@
-<p align="center">
-  <a href="https://github.com/actions/typescript-action/actions"><img alt="typescript-action status" src="https://github.com/actions/typescript-action/workflows/build-test/badge.svg"></a>
-</p>
+# Create a JavaScript Action Using TypeScript
 
-# Create a JavaScript Action using TypeScript
+[![GitHub Super-Linter](https://github.com/actions/typescript-action/actions/workflows/linter.yml/badge.svg)](https://github.com/super-linter/super-linter)
+![CI](https://github.com/actions/typescript-action/actions/workflows/ci.yml/badge.svg)
 
-Use this template to bootstrap the creation of a TypeScript action.:rocket:
+Use this template to bootstrap the creation of a TypeScript action. :rocket:
 
-This template includes compilation support, tests, a validation workflow, publishing, and versioning guidance.  
+This template includes compilation support, tests, a validation workflow,
+publishing, and versioning guidance.
 
-If you are new, there's also a simpler introduction.  See the [Hello World JavaScript Action](https://github.com/actions/hello-world-javascript-action)
+If you are new, there's also a simpler introduction in the
+[Hello world JavaScript action repository](https://github.com/actions/hello-world-javascript-action).
 
-## Create an action from this template
+## Create Your Own Action
 
-Click the `Use this Template` and provide the new repo details for your action
+To create your own action, you can use this repository as a template! Just
+follow the below instructions:
 
-## Code in Main
+1. Click the **Use this template** button at the top of the repository
+1. Select **Create a new repository**
+1. Select an owner and name for your new repository
+1. Click **Create repository**
+1. Clone your new repository
 
-> First, you'll need to have a reasonably modern version of `node` handy. This won't work with versions older than 9, for instance.
+## Initial Setup
 
-Install the dependencies  
-```bash
-$ npm install
-```
+After you've cloned the repository to your local machine or codespace, you'll
+need to perform some initial setup steps before you can develop your action.
 
-Build the typescript and package it for distribution
-```bash
-$ npm run build && npm run package
-```
+> [!NOTE]
+>
+> You'll need to have a reasonably modern version of
+> [Node.js](https://nodejs.org) handy. If you are using a version manager like
+> [`nodenv`](https://github.com/nodenv/nodenv), you can run `nodenv install` in
+> the root of your repository to install the version specified in
+> [`.node-version`](.node-version).
 
-Run the tests :heavy_check_mark:  
-```bash
-$ npm test
+1. :hammer_and_wrench: Install the dependencies
 
- PASS  ./index.test.js
-  ✓ throws invalid number (3ms)
-  ✓ wait 500 ms (504ms)
-  ✓ test runs (95ms)
+   ```bash
+   npm install
+   ```
 
-...
-```
+1. :building_construction: Package the TypeScript for distribution
 
-## Change action.yml
+   ```bash
+   npm run bundle
+   ```
 
-The action.yml defines the inputs and output for your action.
+1. :white_check_mark: Run the tests
 
-Update the action.yml with your name, description, inputs and outputs for your action.
+   ```bash
+   $ npm test
 
-See the [documentation](https://help.github.com/en/articles/metadata-syntax-for-github-actions)
+   PASS  ./index.test.js
+     ✓ throws invalid number (3ms)
+     ✓ wait 500 ms (504ms)
+     ✓ test runs (95ms)
 
-## Change the Code
+   ...
+   ```
 
-Most toolkit and CI/CD operations involve async operations so the action is run in an async function.
+## Update the Action Metadata
 
-```javascript
-import * as core from '@actions/core';
-...
+The [`action.yml`](action.yml) file defines metadata about your action, such as
+input(s) and output(s). For details about this file, see
+[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions).
 
-async function run() {
-  try { 
-      ...
-  } 
-  catch (error) {
-    core.setFailed(error.message);
+**TODO:** Update `action.yml` with the name, description, inputs, and outputs
+for your action.
+
+## Update the Action Code
+
+The [`src/`](./src/) directory is the heart of your action! This contains the
+source code that will be run when your action is invoked. You can replace the
+contents of this directory with your own code.
+
+There are a few things to keep in mind when writing your action code:
+
+- Most GitHub Actions toolkit and CI/CD operations are processed asynchronously.
+  In `index.ts`, you will see that the action is run in an `async` function.
+
+  ```javascript
+  import * as core from '@actions/core';
+  ...
+
+  async function run() {
+    try {
+        ...
+    }
+    catch (error) {
+      core.setFailed(error.message);
+    }
   }
-}
 
-run()
-```
+  run()
+  ```
 
-See the [toolkit documentation](https://github.com/actions/toolkit/blob/master/README.md#packages) for the various packages.
+  For more information about the GitHub Actions toolkit, see the
+  [documentation](https://github.com/actions/toolkit/blob/master/README.md).
 
-## Publish to a distribution branch
+So, what are you waiting for? Go ahead and start customizing your action!
 
-Actions are run from GitHub repos so we will checkin the packed dist folder. 
+1. Create a new branch
 
-Then run [ncc](https://github.com/zeit/ncc) and push the results:
-```bash
-$ npm run package
-$ git add dist
-$ git commit -a -m "prod dependencies"
-$ git push origin releases/v1
-```
+   ```bash
+   git checkout -b releases/v1
+   ```
 
-Note: We recommend using the `--license` option for ncc, which will create a license file for all of the production node modules used in your project.
+1. Replace the contents of `src/` with your action code
+1. Add tests to `__tests__/` for your source code
+1. Format, test, and build the action
 
-Your action is now published! :rocket: 
+   ```bash
+   npm run all
+   ```
 
-See the [versioning documentation](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
+   > [!WARNING]
+   >
+   > This step is important! It will run [`ncc`](https://github.com/vercel/ncc)
+   > to build the final JavaScript action code with all dependencies included.
+   > If you do not run this step, your action will not work correctly when it is
+   > used in a workflow. This step also includes the `--license` option for
+   > `ncc`, which will create a license file for all of the production node
+   > modules used in your project.
 
-## Validate
+1. Commit your changes
 
-You can now validate the action by referencing `./` in a workflow in your repo (see [test.yml](.github/workflows/test.yml))
+   ```bash
+   git add .
+   git commit -m "My first action is ready!"
+   ```
+
+1. Push them to your repository
+
+   ```bash
+   git push -u origin releases/v1
+   ```
+
+1. Create a pull request and get feedback on your action
+1. Merge the pull request into the `main` branch
+
+Your action is now published! :rocket:
+
+For information about versioning your action, see
+[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
+in the GitHub Actions toolkit.
+
+## Validate the Action
+
+You can now validate the action by referencing it in a workflow file. For
+example, [`ci.yml`](./.github/workflows/ci.yml) demonstrates how to reference an
+action in the same repository.
 
 ```yaml
-uses: ./
-with:
-  milliseconds: 1000
+steps:
+  - name: Checkout
+    id: checkout
+    uses: actions/checkout@v3
+
+  - name: Test Local Action
+    id: test-action
+    uses: ./
+    with:
+      milliseconds: 1000
+
+  - name: Print Output
+    id: output
+    run: echo "${{ steps.test-action.outputs.time }}"
 ```
 
-See the [actions tab](https://github.com/actions/typescript-action/actions) for runs of this action! :rocket:
+For example workflow runs, check out the
+[Actions tab](https://github.com/actions/typescript-action/actions)! :rocket:
 
-## Usage:
+## Usage
 
-After testing you can [create a v1 tag](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) to reference the stable and latest V1 action
+After testing, you can create version tag(s) that developers can use to
+reference different stable versions of your action. For more information, see
+[Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md)
+in the GitHub Actions toolkit.
+
+To include the action in a workflow in another repository, you can use the
+`uses` syntax with the `@` symbol to reference a specific branch, tag, or commit
+hash.
+
+```yaml
+steps:
+  - name: Checkout
+    id: checkout
+    uses: actions/checkout@v3
+
+  - name: Test Local Action
+    id: test-action
+    uses: actions/typescript-action@v1 # Commit with the `v1` tag
+    with:
+      milliseconds: 1000
+
+  - name: Print Output
+    id: output
+    run: echo "${{ steps.test-action.outputs.time }}"
+```