Contributing

Dev Container (recommended)

A fully configured dev container is included in .devcontainer/. It comes pre-loaded with the correct Node and pnpm versions, all VS Code extensions, and every other tool needed to work on this project.

Option 1 — VS Code locally: Requires the Dev Containers extension and a local container runtime such as Docker Desktop or Podman. Open the repository and accept the prompt to Reopen in Container.

Option 2 — GitHub Codespaces: Open the repository on GitHub and click Code → Open with Codespaces → New codespace. The same dev container configuration is used, so you get an identical environment in the browser — no local tooling required.

---

Prerequisites

note

These prerequisites apply only if you are not using the dev container.

Tool	Version	Notes
Node	≥ 24	The Dockerfile image uses 26 but only 24 is required
pnpm	≥ 11	Enforced via engines — npm install is blocked
Docker	any	Required to test the action end-to-end locally
git	any	Commit hooks are installed automatically

---

Setup

git clone https://github.com/NSCC-ITC-Assessment/GrillMyCode.git
cd GrillMyCode
pnpm install

pnpm install installs all dependencies and sets up the Husky pre-commit hooks automatically via the prepare script.

---

Running lint and format checks

# Lint source files
pnpm lint

# Auto-fix lint issues
pnpm lint:fix

# Check formatting
pnpm format:check

# Auto-fix formatting
pnpm format

Lint (ESLint) and formatting (Prettier) are also run automatically on staged files before every commit via lint-staged.

---

Type checking

The code is JavaScript, with its types written as JSDoc comments. TypeScript checks them without compiling anything, so the action still runs src/ as it is written.

Each project is checked with its own packages installed, by the same command run from its folder:

# The action (src/)
pnpm typecheck

# The VS Code extension
cd extensions/vscode && pnpm typecheck

# The Workflow Wizard
cd docs-site && pnpm typecheck

All three run on a pull request. They are not part of the pre-commit hooks.

In extensions/vscode/ every parameter must have a type. In src/ and the Workflow Wizard a parameter may still go without one, and is then not checked, so give a type to any parameter of a function you add or change. Shared shapes have a named type to use: Inputs (src/inputs.js), RunState (src/main.js), and WizardConfig and StepProps (the Wizard's index.js).

---

Commit message conventions

This project enforces Conventional Commits via commitlint. Every commit message must follow the pattern:

<type>(<optional scope>): <subject>

Allowed types

Type	When to use
feat	New feature, new input or output
fix	Bug fix
chore	Maintenance, dependency updates, config changes
docs	Documentation only
style	Formatting (no logic change)
refactor	Code change with no behaviour difference
test	Adding or updating tests
perf	Performance improvements
ci	Workflow / CI changes
build	Build system changes
revert	Reverts a previous commit

Rules

• Subject must not be empty and must not end with a period
• Header (type + subject) must be ≤ 100 characters
• Body lines must be ≤ 200 characters

Examples

feat: add anthropic as a supported ai_provider
fix: handle null output when AI returns empty choices array
docs: add Classroom 50 usage example to README
chore: update @actions/core to v3
ci: fix sed quote mismatch in release workflow

---

Pre-commit hooks

Three hooks run automatically:

1. pre-commit — lint-staged runs ESLint and Prettier on staged .js files, and Prettier on staged .json, .yml/.yaml, and .md files. The commit is blocked if any check fails.
2. commit-msg — commitlint validates the commit message against the conventional commit rules above.
3. pre-push — blocks direct pushes to main. Tag pushes (e.g. git push origin v0.14.0) are allowed through so that releases can be triggered from main.

---

Testing locally with Docker

To run the action exactly as it would run in GitHub Actions:

# Build the image
docker build -t grillmycode-local .

# Run it (replace values as appropriate)
docker run --rm \
  -e GITHUB_WORKSPACE=/workspace \
  -e INPUT_GITHUB_TOKEN=<your-token> \
  -e INPUT_API_KEY=<your-openrouter-key> \
  -e INPUT_NUM_QUESTIONS=20 \
  -v $(pwd):/workspace \
  grillmycode-local

note

The action relies on git and a GitHub API token to resolve commit SHAs and post results. For a fully accurate local test, clone a real repository and bind-mount it as the workspace.

---

Branch and PR process

1. Create a feature or fix branch from main:

   git checkout -b feat/my-new-feature

2. Make your changes, commit following the conventions above
3. Push your branch — branch-build.yml triggers automatically, builds a dev Docker image, and pushes it to ghcr.io tagged branch-<sanitized-branch-name>. The workflow can also be triggered manually from the GitHub Actions UI via workflow_dispatch.
4. Open a PR against main and merge when ready

---

Releasing

Releases are triggered by pushing a version tag. See Versioning for the complete guide.