Skip to content

Commit dade0c5

Browse files
authored
Save uncommitted changes (#1312)
1 parent ef0b922 commit dade0c5

1 file changed

Lines changed: 43 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Copilot instructions
2+
3+
## Build, test, and lint
4+
5+
Use Node.js 24 or later (`package.json` declares `>=24.0.0`).
6+
7+
- `npm ci` installs the locked dependencies.
8+
- `npm test` runs Jest serially with coverage.
9+
- `npm test -- --runTestsByPath __tests__/setup-java.test.ts` runs one test file.
10+
- `npm test -- --runTestsByPath __tests__/setup-java.test.ts --testNamePattern="pattern"` filters that file to matching test names.
11+
- `npm run lint` runs ESLint on TypeScript files.
12+
- `npm run format-check` checks Prettier formatting; `npm run format` applies it.
13+
- `npm run build` bundles the setup and post-job entrypoints into `dist/`.
14+
- `npm run check` runs format check, lint, build, and the full test suite.
15+
16+
## Architecture
17+
18+
This repository implements a Node.js GitHub Action. `action.yml` defines its inputs and outputs and runs `dist/setup/index.js` as the main entrypoint and `dist/cleanup/index.js` as the post-job entrypoint. The TypeScript sources in `src/` are bundled with NCC; the committed `dist/` files are what the action executes.
19+
20+
The setup entrypoint parses inputs, resolves versions, and configures the action's shared features. `src/distributions/distribution-factory.ts` lazily selects a vendor installer. Vendor installers implement metadata lookup and archive handling on top of `JavaBase` in `src/distributions/base-installer.ts`, which centralizes version resolution, tool-cache/JDK-cache use, download verification, and Java environment setup. Package support and OS/architecture support are validated centrally in `package-types.ts` and `platform-types.ts`.
21+
22+
The setup flow also configures problem matchers, Maven authentication and arguments, and Maven toolchains. The post-job entrypoint removes any isolated GPG home and saves enabled caches when the job succeeds and cache saving is not read-only.
23+
24+
## Repository-specific conventions
25+
26+
- Keep TypeScript source imports ESM-compatible: relative imports include the `.js` extension, even when the source file is `.ts`.
27+
- Distribution-specific download and metadata logic belongs in its installer under `src/distributions/`; reuse `JavaBase` rather than duplicating common resolution, caching, verification, or environment behavior.
28+
- When adding or changing distribution support, keep the distribution enum, factory, package-capability map, platform-capability map, README support documentation, unit tests, and relevant end-to-end workflow coverage consistent.
29+
- Unit tests live under `__tests__/` and use Jest/ts-jest. Distribution tests are grouped under `__tests__/distributors/`; use the corresponding test and fixture patterns when changing an installer. End-to-end coverage is defined in `.github/workflows/e2e-*.yml`.
30+
- Rebuild and commit generated `dist/` bundles for runtime-affecting source or dependency changes; do not make the bundles the source of truth. `npm run check` includes the build.
31+
- New npm dependencies need lockfile changes and corresponding license records under `.licenses/`, following `.licensed.yml` and the licensed workflow.
32+
33+
## Action behavior principles
34+
35+
- Treat `action.yml` inputs, outputs, defaults, and compatibility aliases as the public API. Keep implementation, README, and advanced-usage documentation aligned when behavior changes; preserve deprecated aliases unless a documented breaking change removes them.
36+
- Do not assume version syntax, package variants, or platform/architecture support is uniform across distributions. Keep capability checks and vendor resolution behavior consistent with the documented support matrix. `latest` means the newest stable GA release, not an early-access build.
37+
- Preserve selection semantics: a recognized vendor in a supported version file may supply the distribution; otherwise the caller must provide it. If both `java-version` and `java-version-file` are given, the explicit `java-version` takes precedence.
38+
- Preserve install-state behavior for multiple JDKs. The last installed JDK becomes the default unless `set-default: false`; all installed JDKs remain available through their version-specific environment variables and Maven toolchains. Toolchain entries accumulate non-destructively, and custom IDs must correspond one-for-one with requested versions.
39+
- Treat dependency, wrapper, and JDK caches as distinct features with distinct keys and save behavior. `cache` enables dependency caching and implicitly enables JDK caching unless `cache-jdk` overrides it; `cache-read-only` restores without saving. Keep changes to cache identity or lifecycle aligned with these documented contracts.
40+
- Preserve download-integrity guarantees: verify authoritative checksums when published. Signature verification is distribution-specific; explicit `verify-signature: true` must enforce verification where supported and fail clearly where unsupported. Do not silently weaken verification or imply that a cached install was downloaded and reverified.
41+
- Keep Maven credential inputs as environment-variable names, not secret values. Generated settings and custom repository behavior must respect the documented overwrite option, while toolchain merging remains non-destructive and independent of that option.
42+
43+
See `docs/CONTRIBUTING.md` for contribution and validation guidance, `README.md` for the public contract, and `docs/advanced-usage.md` for detailed behavior and examples.

0 commit comments

Comments
 (0)