mirror of
https://github.com/awalsh128/cache-apt-pkgs-action.git
synced 2026-07-07 01:24:38 +00:00
72 lines
2.4 KiB
Markdown
72 lines
2.4 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`
|