From 213ec80f5629fd53743a07c81b86deb4c540955f Mon Sep 17 00:00:00 2001
From: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>
Date: Sat, 18 Apr 2026 14:36:59 -0300
Subject: [PATCH] docs: add CONTRIBUTING with pre-commit workflow

Document the docker buildx bake pre-checkin / test / validate sequence
contributors need before pushing, and call out the Alpine-built dist/
gotcha so PRs don't bounce on build-validate.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 CONTRIBUTING.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  4 +++
 2 files changed, 93 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..e333119
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,89 @@
+# Contributing
+
+Thanks for your interest in contributing! This document covers the development
+workflow needed to get a change ready to commit and push.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) with [Buildx](https://docs.docker.com/buildx/working-with-buildx/)
+- Git
+
+That's it. Everything else (Node, npm, linters, the test environment) runs
+inside containers driven by `docker buildx bake`.
+
+## Pre-commit checklist
+
+Run these commands, in order, before committing any change to `src/`,
+`__tests__/`, `package.json`, `package-lock.json`, or `action.yml`:
+
+```sh
+# 1. Format source, refresh node_modules, regenerate dist/index.js
+docker buildx bake pre-checkin
+
+# 2. Run the test suite (unit + integration; needs network for release downloads)
+docker buildx bake test
+
+# 3. Validate that everything is committed and reproducible
+docker buildx bake validate
+```
+
+`validate` is what CI runs. If it passes locally, your PR will pass the
+`validate` job too.
+
+### Why `pre-checkin` matters
+
+The repository ships the compiled action as `dist/index.js`. CI's
+`build-validate` target rebuilds it inside an Alpine container and fails if the
+checked-in bytes don't match. **You must commit the `dist/` output produced by
+`docker buildx bake pre-checkin`** — running `npm run build` on macOS or a
+non-Alpine host produces slightly different bytes and `validate` will reject
+the PR.
+
+If you forget and CI complains about a `dist/` diff, just run:
+
+```sh
+docker buildx bake build
+git add dist/
+git commit --amend --no-edit
+git push --force-with-lease
+```
+
+## Available bake targets
+
+| Target          | Purpose                                             |
+| --------------- | --------------------------------------------------- |
+| `build`         | Regenerate `dist/index.js` only                     |
+| `format`        | Run Prettier on `src/` and `__tests__/`             |
+| `vendor`        | Refresh `node_modules` / `package-lock.json`        |
+| `pre-checkin`   | `vendor` + `format` + `build` (run before commits)  |
+| `lint`          | Prettier check + ESLint                             |
+| `build-validate`| Verify `dist/index.js` matches a fresh build        |
+| `vendor-validate`| Verify `package-lock.json` is in sync               |
+| `validate`      | `lint` + `build-validate` + `vendor-validate`       |
+| `test`          | Run Jest with coverage in an Alpine container       |
+
+## Tests
+
+`docker buildx bake test` runs the full Jest suite, including integration
+tests that:
+
+- Download real GoReleaser releases from GitHub
+- Verify `checksums.txt` against the downloaded archive
+- Verify the cosign sigstore bundle (`cosign` is installed in the test image)
+
+These need outbound network access. If you're behind a restrictive proxy or
+offline, those tests will fail — that's expected.
+
+## Commit messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`,
+`fix:`, `test:`, `docs:`, `chore:`, `ci:`, …). Keep the subject ≤72 chars.
+
+## Pull requests
+
+- Target `master`.
+- Make sure `docker buildx bake validate` and `docker buildx bake test` pass.
+- One logical change per PR is easier to review.
+- The `signing` CI job and `goreleaser-pro` matrix entries are skipped on PRs
+  from forks because they need repository secrets — that's expected and not
+  something you need to fix.
diff --git a/README.md b/README.md
index 13118c9..199093a 100644
--- a/README.md
+++ b/README.md
@@ -233,6 +233,10 @@ If you need the auto-snapshot feature, take a look at [this example repository](
 
 ## Development
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full development workflow.
+
+Quick reference:
+
 ```
 # format code and build javascript artifacts
 docker buildx bake pre-checkin