mirror of
https://github.com/graycoreio/github-actions-magento2.git
synced 2026-06-08 19:46:41 +00:00
Damien Retzinger
112 lines
3.5 KiB
Markdown
112 lines
3.5 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project Overview
|
|
|
|
`github-actions-magento2` — a GitHub Actions toolkit for Magento 2 development. Provides reusable composite actions and reusable workflows that Magento module and store developers call from their own CI pipelines.
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
.github/workflows/ # Reusable workflows and internal CI workflows
|
|
_test/demo-package/ # Test fixture used by internal CI workflows
|
|
docs/ # General documentation
|
|
other-root-level-folders # Individual GitHub Actions (all are external/public)
|
|
```
|
|
|
|
Most actions are **composite** (bash scripts in `action.yml`). Two are **TypeScript bundled**: `supported-version` and `setup-install`.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
# Run all tests
|
|
npm ci
|
|
npm test
|
|
|
|
# Run tests for a single package
|
|
cd actionName && npm test
|
|
|
|
# Build a TypeScript action (must be committed after source changes)
|
|
cd supported-version && npm run build
|
|
cd setup-install && npm run build
|
|
```
|
|
|
|
Build uses `esbuild` and outputs `dist/index.js`. The `dist/` file **must be committed** — GitHub Actions runs the bundled output directly.
|
|
|
|
## Code Style
|
|
|
|
- TypeScript with strict settings
|
|
- ESLint: `eslint:recommended` + `@typescript-eslint/recommended`
|
|
- No comments unless the "why" is non-obvious
|
|
- Conventional commits
|
|
|
|
## Hard Rules (all agents)
|
|
|
|
- Never edit `CHANGELOG.md` — managed by release-please
|
|
- Never commit TypeScript source changes without also committing the rebuilt `dist/index.js`
|
|
- Never add external runtime dependencies to TypeScript actions without flagging bundle size impact
|
|
- Never call `_internal-*` workflows from external repositories
|
|
|
|
---
|
|
|
|
## @test-agent
|
|
|
|
Writes and updates Jest specs for TypeScript actions (`supported-version`, `setup-install`). Scope is limited to `**/*.spec.ts` files.
|
|
|
|
### Style
|
|
|
|
Test observable behavior, not implementation details. No filesystem mocks — use real temp dirs if needed. No network access.
|
|
|
|
```ts
|
|
import { validateKind } from "./validate-kinds";
|
|
|
|
describe('validateKind', () => {
|
|
it('returns `true` if its a valid kind', () => {
|
|
expect(validateKind("latest")).toBe(true);
|
|
});
|
|
|
|
it('throws a helpful exception if its an invalid kind', () => {
|
|
expect(() => validateKind(<any>"taco")).toThrowError();
|
|
});
|
|
});
|
|
```
|
|
|
|
### Never
|
|
|
|
- Test implementation details
|
|
- Mock the filesystem
|
|
- Write tests that require network access
|
|
|
|
---
|
|
|
|
## @supported-version-agent
|
|
|
|
Manages the Magento/Mage-OS version compatibility data in `supported-version/src/versions/`. Scope is limited to those JSON files.
|
|
|
|
### After every edit
|
|
|
|
Run `npm test` inside `supported-version/` before declaring done.
|
|
|
|
### Never
|
|
|
|
- Remove a version entry — only add or mark end-of-life
|
|
- Guess version compatibility — only use data from official Magento/Mage-OS release notes
|
|
- Edit TypeScript source in `supported-version/src/`
|
|
|
|
---
|
|
|
|
## @workflow-agent
|
|
|
|
Owns all externally-facing aspects of the repo: every root-level composite action and the three public reusable workflows (`integration.yaml`, `check-extension.yaml`, `check-store.yaml`). Changes here affect downstream callers.
|
|
|
|
### Boundaries
|
|
|
|
**Free to act** — implementation changes that do not alter the public interface (inputs, outputs, default behavior)
|
|
|
|
**Ask first** — any change to inputs, outputs, or default behavior of an external action or reusable workflow
|
|
|
|
**Never**
|
|
- Remove or rename an existing input/output without a major version bump
|
|
- Change the default value of an existing input
|
|
- Modify `_internal-*` workflows (out of scope)
|
|
- Add a runtime dependency to a TypeScript action without flagging bundle size impact
|