|
| 1 | +# Contributing |
| 2 | + |
| 3 | +## Initial Setup |
| 4 | + |
| 5 | +After you've cloned the repository to your local machine or codespace, you'll |
| 6 | +need to perform some initial setup steps before you can develop your action. |
| 7 | + |
| 8 | +1. Install a [Node.js](https://nodejs.org). If you are using a version manager |
| 9 | + like [`nodenv`](https://github.com/nodenv/nodenv) or |
| 10 | + [`fnm`](https://github.com/Schniz/fnm), thispackage has a `.node-version` |
| 11 | + file at the root of the repository that can be used to automatically switch |
| 12 | + to the correct version when you `cd` into this repository. |
| 13 | + |
| 14 | +2. Install the dependencies |
| 15 | + |
| 16 | + ```bash |
| 17 | + npm install |
| 18 | + ``` |
| 19 | + |
| 20 | +3. Verify the tests pass |
| 21 | + |
| 22 | + ```bash |
| 23 | + $ npm test |
| 24 | + |
| 25 | + PASS __tests__/main.test.ts |
| 26 | + run |
| 27 | + ✓ Sets the version output (30 ms) |
| 28 | + ✓ Sets a failed status (8 ms) |
| 29 | + |
| 30 | + ... |
| 31 | + ``` |
| 32 | + |
| 33 | +## Update the Action Metadata |
| 34 | + |
| 35 | +The [`action.yaml`](./action.yaml) file defines metadata about the action, such |
| 36 | +as input(s) and output(s). For details about this file, see |
| 37 | +[Metadata syntax for GitHub Actions](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions). |
| 38 | + |
| 39 | +## Update the Action Code |
| 40 | + |
| 41 | +1. Create a new branch |
| 42 | + |
| 43 | + ```bash |
| 44 | + git checkout -b js/my-feature |
| 45 | + ``` |
| 46 | + |
| 47 | +2. Make your changes to the action code in `src`. |
| 48 | + |
| 49 | + Any changes to the regular expressions in `src/input.ts` should be reflected |
| 50 | + in the Backus-Naur grammar in the `README.md`. |
| 51 | + |
| 52 | +3. Add tests to `__tests__` for your changes. If you need mock function calls we |
| 53 | + use `nock` for HTTP requests and `jest` for everything else. |
| 54 | + |
| 55 | + If required you may update the `__fixtures__/versions.json` file via |
| 56 | + `curl -fsSL https://julialang-s3.julialang.org/bin/versions.json >__fixtures__/versions.json`. |
| 57 | + Some tests will need to be updated if there are changes to `versions.json`. |
| 58 | + |
| 59 | +4. (Optional) Run the tests |
| 60 | + |
| 61 | + ```bash |
| 62 | + npm test |
| 63 | + ``` |
| 64 | + |
| 65 | +5. (Optional) Test your action locally |
| 66 | + |
| 67 | + The [`@github/local-action`](https://github.com/github/local-action) utility |
| 68 | + can be used to test your action locally. It is a simple command-line tool |
| 69 | + that "stubs" (or simulates) the GitHub Actions Toolkit. This way, you can run |
| 70 | + your TypeScript action locally without having to commit and push your changes |
| 71 | + to a repository. |
| 72 | + |
| 73 | + The `local-action` utility can be run in the following ways: |
| 74 | + |
| 75 | + - Visual Studio Code Debugger |
| 76 | + |
| 77 | + Make sure to review and, if needed, update |
| 78 | + [`.vscode/launch.json`](./.vscode/launch.json) |
| 79 | + |
| 80 | + - Terminal/Command Prompt |
| 81 | + |
| 82 | + ```bash |
| 83 | + # npx local action <action-yaml-path> <entrypoint> <dotenv-file> |
| 84 | + npx local-action . src/main.ts .env |
| 85 | + ``` |
| 86 | + |
| 87 | + You can provide a [`.env`](./.env) file to the `local-action` CLI to set |
| 88 | + environment variables used by the GitHub Actions Toolkit. For example, |
| 89 | + setting inputs and event payload data used by your action. For more |
| 90 | + information see the |
| 91 | + [GitHub Actions Documentation](https://docs.github.com/en/actions/learn-github-actions/variables#default-environment-variables). |
| 92 | + |
| 93 | +6. Format, test, and build the action |
| 94 | + |
| 95 | + ```bash |
| 96 | + npm run all |
| 97 | + ``` |
| 98 | + |
| 99 | + > This step is important! It will run [`rollup`](https://rollupjs.org/) to |
| 100 | + > build the final JavaScript action code with all dependencies included. If |
| 101 | + > you do not run this step, your pushed changes will not work correctly when |
| 102 | + > it is used in a workflow. |
| 103 | + |
| 104 | +7. Commit your changes |
| 105 | + |
| 106 | + ```bash |
| 107 | + git add . |
| 108 | + git commit -m "My feature" |
| 109 | + ``` |
| 110 | + |
| 111 | +8. Push your changes |
| 112 | + |
| 113 | + ```bash |
| 114 | + git push |
| 115 | + ``` |
| 116 | + |
| 117 | +9. Create a pull request and wait for feedback or approval |
| 118 | +10. Merge the pull request into the `main` branch |
| 119 | + |
| 120 | +Your action changes are now published! :rocket: |
| 121 | + |
| 122 | +## Publishing a New Release |
| 123 | + |
| 124 | +This action follows the standard procedures around |
| 125 | +[versioning GitHub Actions](https://github.com/actions/toolkit/blob/master/docs/action-versioning.md). |
| 126 | +The helper script, [`script/release`](./script/release) is used to streamline |
| 127 | +the process of tagging and pushing new releases for GitHub Actions. |
| 128 | + |
| 129 | +GitHub Actions allows users to select a specific version of the action to use, |
| 130 | +based on release tags. This script simplifies this process by performing the |
| 131 | +following steps: |
| 132 | + |
| 133 | +1. **Retrieving the latest release tag:** The script starts by fetching the most |
| 134 | + recent SemVer release tag of the current branch, by looking at the local data |
| 135 | + available in your repository. |
| 136 | +2. **Prompting for a new release tag:** The user is then prompted to enter a new |
| 137 | + release tag. To assist with this, the script displays the tag retrieved in |
| 138 | + the previous step, and validates the format of the inputted tag (vX.X.X). The |
| 139 | + user is also reminded to update the version field in package.json. |
| 140 | +3. **Tagging the new release:** The script then tags a new release and syncs the |
| 141 | + separate major tag (e.g. v1, v2) with the new release tag (e.g. v1.0.0, |
| 142 | + v2.1.2). When the user is creating a new major release, the script |
| 143 | + auto-detects this and creates a `releases/v#` branch for the previous major |
| 144 | + version. |
| 145 | +4. **Pushing changes to remote:** Finally, the script pushes the necessary |
| 146 | + commits, tags and branches to the remote repository. From here, you will need |
| 147 | + to create a new release in GitHub so users can easily reference the new tags |
| 148 | + in their workflows. |
| 149 | + |
| 150 | +## Dependency License Management |
| 151 | + |
| 152 | +This template includes a GitHub Actions workflow, |
| 153 | +[`licensed.yaml`](./.github/workflows/licensed.yaml), that uses |
| 154 | +[Licensed](https://github.com/licensee/licensed) to check for dependencies with |
| 155 | +missing or non-compliant licenses. Currently this workflow is initially |
| 156 | +disabled. To enable the workflow, follow the below steps. |
| 157 | + |
| 158 | +1. Open [`licensed.yaml`](./.github/workflows/licensed.yaml) |
| 159 | +2. Uncomment the following lines: |
| 160 | + |
| 161 | + ```yaml |
| 162 | + # pull_request: |
| 163 | + # branches: |
| 164 | + # - main |
| 165 | + # push: |
| 166 | + # branches: |
| 167 | + # - main |
| 168 | + ``` |
| 169 | + |
| 170 | +3. Save and commit the changes |
| 171 | + |
| 172 | +Once complete, this workflow will run any time a pull request is created or |
| 173 | +changes pushed directly to `main`. If the workflow detects any dependencies with |
| 174 | +missing or non-compliant licenses, it will fail the workflow and provide details |
| 175 | +on the issue(s) found. |
| 176 | + |
| 177 | +### Updating Licenses |
| 178 | + |
| 179 | +Whenever you install or update dependencies, you can use the Licensed CLI to |
| 180 | +update the licenses database. To install Licensed, see the project's |
| 181 | +[Readme](https://github.com/licensee/licensed?tab=readme-ov-file#installation). |
| 182 | +
|
| 183 | +To update the cached licenses, run the following command: |
| 184 | +
|
| 185 | +```bash |
| 186 | +licensed cache |
| 187 | +``` |
| 188 | +
|
| 189 | +To check the status of cached licenses, run the following command: |
| 190 | +
|
| 191 | +```bash |
| 192 | +licensed status |
| 193 | +``` |
0 commit comments