mirror of
https://github.com/ivuorinen/actions.git
synced 2026-02-14 09:47:36 +00:00
Ismo Vuorinen
7061aafd35
* docs: update documentation * feat: validate-inputs has it's own pyproject * security: mask DOCKERHUB_PASSWORD * chore: add tokens, checkout, recrete docs, integration tests * fix: add `statuses: write` permission to pr-lint
102 lines
2.8 KiB
Markdown
102 lines
2.8 KiB
Markdown
# Documentation Guide
|
|
|
|
## Documentation Locations
|
|
|
|
### Validation System Docs (`validate-inputs/docs/`)
|
|
|
|
Read when working with validators or validation logic:
|
|
|
|
**API.md** - Complete API reference
|
|
|
|
- BaseValidator methods and properties
|
|
- Core validators (Boolean, Version, Token, Numeric, Docker, File, Network, Security, CodeQL)
|
|
- Registry system usage
|
|
- Custom validator patterns
|
|
- Convention system
|
|
|
|
**DEVELOPER_GUIDE.md** - Creating new validators
|
|
|
|
- Quick start guide
|
|
- Creating core validators (in validators/ directory)
|
|
- Creating custom validators (in action directories)
|
|
- Adding convention patterns
|
|
- Writing tests, debugging, common patterns
|
|
|
|
**ACTION_MAINTAINER.md** - Using validation in actions
|
|
|
|
- How validation works (automatic integration)
|
|
- Validation flow (input collection, validator selection, execution, error reporting)
|
|
- Using automatic validation via conventions
|
|
- Custom validation for complex scenarios
|
|
- Testing validation, common scenarios, troubleshooting
|
|
|
|
**README_ARCHITECTURE.md** - System architecture
|
|
|
|
- Feature overview
|
|
- Quick start examples
|
|
- Architecture details
|
|
- Modular validator structure
|
|
- Convention-based detection
|
|
- Custom validator support
|
|
|
|
### Testing Framework (`_tests/README.md`)
|
|
|
|
Read when writing or debugging tests:
|
|
|
|
- ShellSpec framework overview
|
|
- Multi-level testing strategy (unit, integration, external usage)
|
|
- Directory structure explanation
|
|
- Test writing patterns
|
|
- Running tests (`make test`, `make test-unit`, `make test-action ACTION=name`)
|
|
- Coverage reporting
|
|
- Mocking and fixtures
|
|
- CI integration
|
|
|
|
### Docker Testing Tools (`_tools/docker-testing-tools/README.md`)
|
|
|
|
Read when working with CI or testing infrastructure:
|
|
|
|
- Pre-built Docker image with all testing tools
|
|
- Pre-installed tools (ShellSpec, nektos/act, TruffleHog, actionlint, etc.)
|
|
- Building locally (build.sh, test.sh)
|
|
- Performance benefits (saves ~3 minutes per run)
|
|
- Multi-stage build process
|
|
- Usage in workflows
|
|
|
|
### Top-Level Documentation
|
|
|
|
**README.md** - Main project readme (auto-generated)
|
|
|
|
- Actions catalog
|
|
- Usage examples
|
|
- Quick reference
|
|
|
|
**SECURITY.md** - Security policy
|
|
|
|
- Reporting vulnerabilities
|
|
- Security practices
|
|
|
|
**LICENSE.md** - MIT license
|
|
|
|
**CLAUDE.md** - Project instructions (covered in development_standards memory)
|
|
|
|
## When to Read What
|
|
|
|
**Starting new validator work**: Read `DEVELOPER_GUIDE.md`, then `API.md` for reference
|
|
|
|
**Using validation in action**: Read `ACTION_MAINTAINER.md`
|
|
|
|
**Understanding architecture**: Read `README_ARCHITECTURE.md`
|
|
|
|
**Writing tests**: Read `_tests/README.md`
|
|
|
|
**Setting up CI/testing**: Read `_tools/docker-testing-tools/README.md`
|
|
|
|
**API reference lookup**: Read `API.md` (has method tables, validator details)
|
|
|
|
## Documentation is Auto-Generated
|
|
|
|
- Action READMEs generated via `action-docs` (don't edit manually)
|
|
- Validation system README auto-generated
|
|
- Keep CLAUDE.md and docs/ files updated manually
|