diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..d6c0b1a8 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,84 @@ +## Development workflow + +### 1. Install tools + +#### Node.js + +[**npm**](https://www.npmjs.com/) is used for dependency management. + +Follow the installation instructions here:
+https://nodejs.dev/en/download + +### 2. Install dependencies + +To work on the codebase you have to install all the dependencies: + +``` +npm install +``` + +### 3. Coding + +Now you're ready to work some [TypeScript](https://www.typescriptlang.org/) magic! + +Make sure to write or update tests for your work when appropriate. + +### 4. Format code + +Format the code to follow the standard style for the project: + +``` +npm run format +``` + +### 5. Run tests + +To run the tests: + +``` +npm run test +``` + +### 6. Build + +It is necessary to compile the code before it can be used by GitHub Actions. We check in the `node_modules` to provide runtime dependencies to the system using the Action, so be careful not to `git add` all the development dependencies you might have under your local `node_modules`. +Remember to run these commands before committing any code changes: + +``` +npm run build +``` + +remove all the dependencies: + +``` +rm -rf node_modules +``` + +add back **only** the runtime dependencies: + +``` +npm install --production +``` + +check in the code that matters: + +``` +git add lib node_modules +``` + +### 7. Commit + +Everything is now ready to make your contribution to the project, so commit it to the repository and submit a pull request. + +Thanks! + +## Release workflow + +To release a new version of the Action the workflow should be the following: + +1. If the release will increment the major version, update the action refs in the examples in README.md + (e.g., `uses: arduino/setup-protoc@v1` -> `uses: arduino/setup-protoc@v2`). +1. open a PR and request a review. +1. After PR is merged, create a release, following the `vX.X.X` tag name convention. +1. After the release, rebase the release branch for that major version (e.g., `v1` branch for the v1.x.x tags) on the tag. + If no branch exists for the release's major version, create one. diff --git a/.github/workflows/check-packaging-ncc-typescript-npm.yml b/.github/workflows/check-packaging-ncc-typescript-npm.yml new file mode 100644 index 00000000..bca774a8 --- /dev/null +++ b/.github/workflows/check-packaging-ncc-typescript-npm.yml @@ -0,0 +1,52 @@ +name: Check Packaging + +env: + # See: https://github.com/actions/setup-node/#readme + NODE_VERSION: 16.x + +on: + push: + paths: + - ".github/workflows/check-packaging-ncc-typescript-npm.ya?ml" + - "lerna.json" + - "package.json" + - "package-lock.json" + - "Taskfile.ya?ml" + - "tsconfig.json" + - "**.[jt]sx?" + pull_request: + paths: + - ".github/workflows/check-packaging-ncc-typescript-npm.ya?ml" + - "lerna.json" + - "package.json" + - "package-lock.json" + - "Taskfile.ya?ml" + - "tsconfig.json" + - "**.[jt]sx?" + workflow_dispatch: + repository_dispatch: + +jobs: + check-packaging: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: ${{ env.NODE_VERSION }} + + - name: Install dependencies + run: npm install + + - name: Build project + run: | + npm run build + + - name: Check packaging + # Ignoring CR because ncc's output has a mixture of line endings, while the repository should only contain + # Unix-style EOL. + run: git diff --ignore-cr-at-eol --color --exit-code lib diff --git a/README.md b/README.md index b9777489..b39663d5 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ [![Check npm status](https://github.com/arduino/setup-protoc/actions/workflows/check-npm-task.yml/badge.svg)](https://github.com/arduino/setup-protoc/actions/workflows/check-npm-task.yml) [![Check TypeScript status](https://github.com/arduino/setup-protoc/actions/workflows/check-typescript-task.yml/badge.svg)](https://github.com/arduino/setup-protoc/actions/workflows/check-typescript-task.yml) [![Check tsconfig status](https://github.com/arduino/setup-protoc/actions/workflows/check-tsconfig-task.yml/badge.svg)](https://github.com/arduino/setup-protoc/actions/workflows/check-tsconfig-task.yml) +[![Check Packaging status](https://github.com/arduino/setup-protoc/actions/workflows/check-packaging-ncc-typescript-npm.yml/badge.svg)](https://github.com/arduino/setup-protoc/actions/workflows/check-packaging-ncc-typescript-npm.yml) This action makes the `protoc` compiler available to Workflows. @@ -28,7 +29,7 @@ If you want to pin a major or minor version you can use the `.x` wildcard: - name: Install Protoc uses: arduino/setup-protoc@v1 with: - version: '3.x' + version: "3.x" ``` You can also require to include releases marked as `pre-release` in Github using the `include-pre-releases` flag (the dafault value for this flag is `false`) @@ -37,7 +38,7 @@ You can also require to include releases marked as `pre-release` in Github using - name: Install Protoc uses: arduino/setup-protoc@v1 with: - version: '3.x' + version: "3.x" include-pre-releases: true ``` @@ -47,7 +48,7 @@ To pin the exact version: - name: Install Protoc uses: arduino/setup-protoc@v1 with: - version: '3.9.1' + version: "3.9.1" ``` The action queries the GitHub API to fetch releases data, to avoid rate limiting, @@ -60,50 +61,12 @@ pass the default token with the `repo-token` variable: repo-token: ${{ secrets.GITHUB_TOKEN }} ``` - -## Development - -To work on the codebase you have to install all the dependencies: - -```sh -# npm install -``` - -To run the tests: - -```sh -# npm run test -``` - ## Enable verbose logging for a pipeline + Additional log events with the prefix ::debug:: can be enabled by setting the secret `ACTIONS_STEP_DEBUG` to `true`. See [step-debug-logs](https://github.com/actions/toolkit/blob/master/docs/action-debugging.md#step-debug-logs) for reference. - - -## Release - -We check in the `node_modules` to provide runtime dependencies to the system -using the Action, so be careful not to `git add` all the development dependencies -you might have under your local `node_modules`. To release a new version of the -Action the workflow should be the following: - -1. `npm install` to add all the dependencies, included development. -1. `npm run test` to see everything works as expected. -1. `npm run build` to build the Action under the `./lib` folder. -1. `rm -rf node_modules` to remove all the dependencies. -1. `npm install --production` to add back **only** the runtime dependencies. -1. `git add lib node_modules` to check in the code that matters. -1. If the release will increment the major version, update the action refs in the examples in README.md - (e.g., `uses: arduino/setup-protoc@v1` -> `uses: arduino/setup-protoc@v2`). -1. open a PR and request a review. -1. After PR is merged, create a release, following the `vX.X.X` tag name convention. -1. After the release, rebase the release branch for that major version (e.g., `v1` branch for the v1.x.x tags) on the tag. - If no branch exists for the release's major version, create one. - - - ## Security If you think you found a vulnerability or other security-related bug in this project, please read our @@ -111,3 +74,9 @@ If you think you found a vulnerability or other security-related bug in this pro Thank you! e-mail contact: security@arduino.cc + +## Contributing + +To report bugs or make feature requests, please submit an issue: https://github.com/arduino/setup-protoc/issues + +Pull requests are welcome! Please see the [contribution guidelines](.github/CONTRIBUTING.md) for information.