cache-apt-pkgs-action/CONTRIBUTIONS.md

Contributions

Thank you for contributing to this project.

Scope

This document defines contribution expectations for code quality, testing, and documentation.

Quick Start

1. Fork and create a feature branch from v2-ts.
2. Make focused, minimal, reversible changes.
3. Run relevant checks before opening a PR.
4. Open a PR with a clear summary and validation notes.

Development Standards

1. Preserve existing architecture unless a change is explicitly requested.
2. Keep naming consistent for semantically identical constructs.
3. Prefer explicit failures with actionable errors.
4. Avoid changing public API or externally observable behavior unless requested.

Documentation Standards

Apply these standards to all exported/public APIs in src/:

1. Use TSDoc blocks (/** ... */) with concise behavior-focused summaries.
2. Include explicit @param tags for each input parameter.
3. Include explicit @returns tags for return values (or Nothing for void).
4. Include @throws when the function intentionally throws validation/runtime errors.
5. Prefer documenting behavior and constraints over implementation detail.
6. Keep comments synchronized with current behavior; update docs in the same change as code.

Testing Standards

1. Test naming format: <method> <conditions> <expected>.
2. Test behavior, not implementation detail.
3. Keep setup focused on the tested condition.
4. Avoid control-flow logic (if, loops) in test bodies.
5. Add or update tests for any behavior change in the same PR.

Verification Before PR

Run the smallest relevant checks first, then broader checks as needed:

npm run typecheck
npm exec vitest run test/action.test.ts test/action-runner.test.ts test/manifest.test.ts test/io.test.ts

When changing scripts under scripts/dev/ or scripts/ops/, also run:

npm exec vitest run test/dev_scripts.test.ts

Pull Request Checklist

1. Change scope is clear and minimal.
2. Documentation updated for exported/public API changes.
3. Tests added/updated for behavior changes.
4. Verification commands listed with pass/fail status.
5. No secrets or credentials are included.

Commit Message Guidance

Use concise, imperative messages, for example:

• docs: standardize TSDoc across src APIs
• test: add coverage for ActionRunner cache-hit branch
• refactor: move reusable script library to repository root