generated from actions/typescript-action
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
First version containing
- basic functionality
- Inputs:
- githubToken:
- userDocsDirs:
- recurseUserDocDirs:
- docFileExtensions:
- srcFileExtensions:
- >90% test coverage
- Readme- Loading branch information
Showing
23 changed files
with
30,696 additions
and
1,106 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,10 @@ | ||
| # Unordered list style | ||
| # All items in unordered lists should start with '-' | ||
| MD004: | ||
| style: dash | ||
|
|
||
| # Ordered list item prefix | ||
| # Disable line limits | ||
| MD013: false | ||
|
|
||
| # All items in ordered list should be numbered as '1.' | ||
| MD029: | ||
| style: one |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Validating CODEOWNERS rules …
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,2 @@ | ||
| # Repository CODEOWNERS | ||
|
|
||
| * @actions/actions-runtime | ||
| * @ncalteen |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,230 +1,84 @@ | ||
| # Create a GitHub Action Using TypeScript | ||
| # DocTagChecker | ||
|
|
||
| [](https://github.com/super-linter/super-linter) | ||
|  | ||
| [](https://github.com/actions/typescript-action/actions/workflows/check-dist.yml) | ||
| [](https://github.com/actions/typescript-action/actions/workflows/codeql-analysis.yml) | ||
| [](https://github.com/super-linter/super-linter) | ||
|  | ||
| [](https://github.com/AutoPas/DocTagChecker/actions/workflows/check-dist.yml) | ||
| [](https://github.com/AutoPas/DocTagChecker/actions/workflows/codeql-analysis.yml) | ||
| [](./badges/coverage.svg) | ||
|
|
||
| Use this template to bootstrap the creation of a TypeScript action. :rocket: | ||
| An GitHub action to help you keep your user documentation up to date with your source code. | ||
|
|
||
| This template includes compilation support, tests, a validation workflow, | ||
| publishing, and versioning guidance. | ||
| It works by looking for file or directory tags in your documentation and then checking if these documentation pages are changed if the linked source code is updated. | ||
| Since this is very prone to false-positives it does never fail workflows but instead post status comments to the corresponding pull request. | ||
|
|
||
| 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 Your Own Action | ||
|
|
||
| To create your own action, you can use this repository as a template! Just | ||
| follow the below instructions: | ||
|
|
||
| 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 | ||
|
|
||
| > [!IMPORTANT] | ||
| > | ||
| > Make sure to remove or update the [`CODEOWNERS`](./CODEOWNERS) file! For | ||
| > details on how to use this file, see | ||
| > [About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners). | ||
| ## Initial Setup | ||
|
|
||
| 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. | ||
|
|
||
| > [!NOTE] | ||
| > | ||
| > You'll need to have a reasonably modern version of | ||
| > [Node.js](https://nodejs.org) handy (20.x or later should work!). If you are | ||
| > using a version manager like [`nodenv`](https://github.com/nodenv/nodenv) or | ||
| > [`nvm`](https://github.com/nvm-sh/nvm), this template has a `.node-version` | ||
| > file at the root of the repository that will be used to automatically switch | ||
| > to the correct version when you `cd` into the repository. Additionally, this | ||
| > `.node-version` file is used by GitHub Actions in any `actions/setup-node` | ||
| > actions. | ||
| 1. :hammer_and_wrench: Install the dependencies | ||
|
|
||
| ```bash | ||
| npm install | ||
| ``` | ||
|
|
||
| 1. :building_construction: Package the TypeScript for distribution | ||
|
|
||
| ```bash | ||
| npm run bundle | ||
| ``` | ||
|
|
||
| 1. :white_check_mark: Run the tests | ||
|
|
||
| ```bash | ||
| $ npm test | ||
|
|
||
| PASS ./index.test.js | ||
| ✓ throws invalid number (3ms) | ||
| ✓ wait 500 ms (504ms) | ||
| ✓ test runs (95ms) | ||
|
|
||
| ... | ||
| ``` | ||
|
|
||
| ## Update the Action Metadata | ||
|
|
||
| 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). | ||
|
|
||
| When you copy this repository, 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 `main.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) | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| For more information about the GitHub Actions toolkit, see the | ||
| [documentation](https://github.com/actions/toolkit/blob/master/README.md). | ||
|
|
||
| So, what are you waiting for? Go ahead and start customizing your action! | ||
|
|
||
| 1. Create a new branch | ||
| ## Usage | ||
|
|
||
| ```bash | ||
| git checkout -b releases/v1 | ||
| ``` | ||
| To use DocTagChecker in your project, you need to include it and adhere to its (very few) assumptions. | ||
|
|
||
| 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 | ||
| ### Add DocTagChecker to your Workflows | ||
|
|
||
| ```bash | ||
| npm run all | ||
| ``` | ||
| To add this action to your CI copy and adapt the following into your `YAML` workflow file. | ||
|
|
||
| > [!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. | ||
| ```yaml | ||
| jobs: | ||
| DocTagCheck: | ||
| steps: | ||
| - name: Checkout your code | ||
| uses: your/way/to/checkout | ||
| - name: Check for missing userdoc updates | ||
| uses: AutoPas/DocTagChecker@main # substitute main for a release tag | ||
| with: | ||
| githubToken: ${{ secrets.GITHUB_TOKEN }} | ||
| # multiple paths are separated by whitespace or ',' | ||
| userDocsDirs: paths/to/ your/doc/dir relative/to/repo/root | ||
| # Optional inputs with defaults: | ||
| # Check userDocsDirs recursively. | ||
| recurseUserDocDirs: false | ||
| # File extensions for files to be considered documentation. | ||
| docFileExtensions: md | ||
| # File extensions for files to be considered source code. | ||
| srcFileExtensions: cpp h txt | ||
| ``` | ||
| 1. Commit your changes | ||
| ### Tag your Documentation | ||
| ```bash | ||
| git add . | ||
| git commit -m "My first action is ready!" | ||
| ``` | ||
| DocTagChecker looks for two kinds of tags in all documentation files: | ||
| 1. Push them to your repository | ||
| - **File Tags**: Any filename that occurs in the file. A filename is a string without white spaces that ends with a file ending. File tags do not include paths. | ||
| - **Directory Tags**: Any path that occurs after the string "Related Files and Folders", so it is advised to create such a section at the end of every documentation page. A path is a string without white spaces that ends with a `/`. It can be absolute or relative to the root of the repository. Everything in the tagged directory will be recursively added to the file tags. | ||
|
|
||
| ```bash | ||
| git push -u origin releases/v1 | ||
| ``` | ||
| ## Build and Develop | ||
|
|
||
| 1. Create a pull request and get feedback on your action | ||
| 1. Merge the pull request into the `main` branch | ||
| This GitHub action was created from the [actions/typescrip-action template](https://github.com/actions/typescript-action). Refer to this for general tips, techniques, and guidelines. | ||
|
|
||
| Your action is now published! :rocket: | ||
| ### Dependencies | ||
|
|
||
| For information about versioning your action, see | ||
| [Versioning](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md) | ||
| in the GitHub Actions toolkit. | ||
| - [Node.js](https://nodejs.org) Version >= 20 | ||
|
|
||
| ## Validate the Action | ||
| ### Development Workflow | ||
|
|
||
| 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. | ||
| The general development workflow should look as follows: | ||
|
|
||
| ```yaml | ||
| steps: | ||
| - name: Checkout | ||
| id: checkout | ||
| uses: actions/checkout@v4 | ||
|
|
||
| - name: Test Local Action | ||
| id: test-action | ||
| uses: ./ | ||
| with: | ||
| milliseconds: 1000 | ||
|
|
||
| - name: Print Output | ||
| id: output | ||
| run: echo "${{ steps.test-action.outputs.time }}" | ||
| ``` | ||
| 1. Create a new branch for your update | ||
|
|
||
| For example workflow runs, check out the | ||
| [Actions tab](https://github.com/actions/typescript-action/actions)! :rocket: | ||
| ```bash | ||
| git checkout -b myAwsomeUpdate | ||
| ``` | ||
|
|
||
| ## Usage | ||
| 1. Implement your update in [`src/`](src) in TypeScript. | ||
|
|
||
| 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. | ||
| If you need new input values for the action, add them to [`action.yml`](action.yml) | ||
| 1. Add tests to [`__tests__`](__tests__). | ||
| 1. Format, build, and run the tests. | ||
|
|
||
| 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. | ||
| ```bash | ||
| npm run all | ||
| ``` | ||
|
|
||
| ```yaml | ||
| steps: | ||
| - name: Checkout | ||
| id: checkout | ||
| uses: actions/checkout@v4 | ||
| - 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 }}" | ||
| ``` | ||
| This is critical. Without this step the JavaScript code, which is what's actually run, is not built and nothing changes! | ||
| 1. Commit, push, review, merge to main. | ||
| 1. (If applicable) Create a new release using the [release script](script/release). | ||
|
|
||
| ## Publishing a new release | ||
| This project includes a helper script designed to streamline the process of | ||
| tagging and pushing new releases for GitHub Actions. | ||
| GitHub Actions allows users to select a specific version of the action to use, | ||
| based on release tags. Our script simplifies this process by performing the | ||
| following steps: | ||
| 1. **Retrieving the latest release tag:** The script starts by fetching the most | ||
| recent release tag by looking at the local data available in your repository. | ||
| 1. **Prompting for a new release tag:** The user is then prompted to enter a new | ||
| release tag. To assist with this, the script displays the latest release tag | ||
| and provides a regular expression to validate the format of the new tag. | ||
| 1. **Tagging the new release:** Once a valid new tag is entered, the script tags | ||
| the new release. | ||
| 1. **Pushing the new tag to the remote:** Finally, the script pushes the new tag | ||
| to the remote repository. From here, you will need to create a new release in | ||
| GitHub and users can easily reference the new tag in their workflows. | ||
| ```bash | ||
| script/release | ||
| ``` |
Oops, something went wrong.