mirror of
https://github.com/actions/container-toolkit-action.git
synced 2025-12-10 03:46:47 +00:00
132 lines
5.4 KiB
Markdown
132 lines
5.4 KiB
Markdown
# Copilot Instructions
|
|
|
|
This GitHub Action is written in TypeScript and transpiled to JavaScript. The
|
|
transpiled JavaScript is invoked from within a Docker container. Both the
|
|
TypeScript sources and the **generated** JavaScript code are contained in this
|
|
repository. The TypeScript sources are contained in the `src` directory and the
|
|
JavaScript code is contained in the `dist` directory. A GitHub Actions workflow
|
|
checks that the JavaScript code in `dist` is up-to-date. Therefore, you should
|
|
not review any changes to the contents of the `dist` folder and it is expected
|
|
that the JavaScript code in `dist` closely mirrors the TypeScript code it is
|
|
generated from.
|
|
|
|
## Repository Structure
|
|
|
|
| Path | Description |
|
|
| -------------------- | ----------------------------------- |
|
|
| `__fixtures__/` | Unit Test Fixtures |
|
|
| `__tests__/` | Unit Tests |
|
|
| `.devcontainer/` | Development Container Configuration |
|
|
| `.github/` | GitHub Configuration |
|
|
| `.licenses/` | License Information |
|
|
| `.vscode/` | Visual Studio Code Configuration |
|
|
| `badges/` | Badges for readme |
|
|
| `dist/` | Generated JavaScript Code |
|
|
| `src/` | TypeScript Source Code |
|
|
| `.licensed.yml` | Licensed Configuration |
|
|
| `.markdown-lint.yml` | Markdown Linter Configuration |
|
|
| `.node-version` | Node.js Version Configuration |
|
|
| `.prettierrc.yml` | Prettier Formatter Configuration |
|
|
| `.yaml-lint.yml` | YAML Linter Configuration |
|
|
| `action.yml` | GitHub Action Metadata |
|
|
| `CODEOWNERS` | Code Owners File |
|
|
| `Dockerfile` | Dockerfile for the Action |
|
|
| `eslint.config.mjs` | ESLint Configuration |
|
|
| `jest.config.js` | Jest Configuration |
|
|
| `LICENSE` | License File |
|
|
| `package.json` | NPM Package Configuration |
|
|
| `README.md` | Project Documentation |
|
|
| `rollup.config.ts` | Rollup Bundler Configuration |
|
|
| `tsconfig.json` | TypeScript Configuration |
|
|
|
|
## Environment Setup
|
|
|
|
Install dependencies by running:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Testing
|
|
|
|
Ensure all unit tests pass by running:
|
|
|
|
```bash
|
|
npm run test
|
|
```
|
|
|
|
Unit tests should exist in the `__tests__` directory. They are powered by
|
|
`jest`. Fixtures should be placed in the `__fixtures__` directory.
|
|
|
|
## Bundling
|
|
|
|
Any time files in the `src` directory are changed, you should run the following
|
|
command to bundle the TypeScript code into JavaScript:
|
|
|
|
```bash
|
|
npm run bundle
|
|
```
|
|
|
|
## General Coding Guidelines
|
|
|
|
- Follow standard TypeScript and JavaScript coding conventions and best
|
|
practices
|
|
- Changes should maintain consistency with existing patterns and style
|
|
- Document changes clearly and thoroughly, including updates to existing
|
|
comments when appropriate
|
|
- Do not include basic, unnecessary comments that simply restate what the code
|
|
is doing (focus on explaining _why_, not _what_)
|
|
- Use consistent error handling patterns throughout the codebase
|
|
- Use TypeScript's type system to ensure type safety and clarity
|
|
- Keep functions focused and manageable
|
|
- Use descriptive variable and function names that clearly convey their purpose
|
|
- Use JSDoc comments to document functions, classes, and complex logic
|
|
- After doing any refactoring, ensure to run `npm run test` to ensure that all
|
|
tests still pass and coverage requirements are met
|
|
- When suggesting code changes, always opt for the most maintainable approach.
|
|
Try your best to keep the code clean and follow "Don't Repeat Yourself" (DRY)
|
|
principles
|
|
- Avoid unnecessary complexity and always consider the long-term maintainability
|
|
of the code
|
|
- When writing unit tests, try to consider edge cases as well as the main path
|
|
of success. This will help ensure that the code is robust and can handle
|
|
unexpected inputs or situations
|
|
- Use the `@actions/core` package for logging over `console` to ensure
|
|
compatibility with GitHub Actions logging features
|
|
|
|
### Versioning
|
|
|
|
GitHub Actions are versioned using branch and tag names. Please ensure the
|
|
version in the project's `package.json` is updated to reflect the changes made
|
|
in the codebase. The version should follow
|
|
[Semantic Versioning](https://semver.org/) principles.
|
|
|
|
## Pull Request Guidelines
|
|
|
|
When creating a pull request (PR), please ensure that:
|
|
|
|
- Keep changes focused and minimal (avoid large changes, or consider breaking
|
|
them into separate, smaller PRs)
|
|
- Formatting checks pass
|
|
- Linting checks pass
|
|
- Unit tests pass and coverage requirements are met
|
|
- The action has been transpiled to JavaScript and the `dist` directory is
|
|
up-to-date with the latest changes in the `src` directory
|
|
- If necessary, the `README.md` file is updated to reflect any changes in
|
|
functionality or usage
|
|
|
|
The body of the PR should include:
|
|
|
|
- A summary of the changes
|
|
- A special note of any changes to dependencies
|
|
- A link to any relevant issues or discussions
|
|
- Any additional context that may be helpful for reviewers
|
|
|
|
## Code Review Guidelines
|
|
|
|
When performing a code review, please follow these guidelines:
|
|
|
|
- If there are changes that modify the functionality/usage of the action,
|
|
validate that there are changes in the `README.md` file that document the new
|
|
or modified functionality
|