From a5129e99f44f5d2ba22cdc54770745bd6f0d9c33 Mon Sep 17 00:00:00 2001 From: Kevin Stillhammer Date: Sat, 11 Oct 2025 19:18:50 +0200 Subject: [PATCH] Add copilot-instructions.md (#630) --- .github/copilot-instructions.md | 263 ++++++++++++++++++++++++++++++++ .gitignore | 3 + 2 files changed, 266 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..64664d2 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,263 @@ +# Copilot Instructions for setup-uv + +This document provides essential information for GitHub Copilot coding agents working on the `astral-sh/setup-uv` repository. + +## Repository Overview + +**setup-uv** is a GitHub Action that sets up the [uv](https://docs.astral.sh/uv/) +Python package installer in GitHub Actions workflows. +It's a TypeScript-based action that downloads uv binaries, manages caching, handles version resolution, +and configures the environment for subsequent workflow steps. + +### Key Features + +- Downloads and installs specific uv versions from GitHub releases +- Supports version resolution from config files (pyproject.toml, uv.toml, .tool-versions) +- Implements intelligent caching for both uv cache and Python installations +- Provides cross-platform support (Linux, macOS, Windows, including ARM architectures) +- Includes problem matchers for Python error reporting +- Supports environment activation and custom tool directories + +## Repository Structure + +**Size**: Small-medium repository (~50 source files, ~400 total files including dependencies) +**Languages**: TypeScript (primary), JavaScript (compiled output), JSON (configuration) +**Runtime**: Node.js 24 (GitHub Actions runtime) +**Key Dependencies**: @actions/core, @actions/cache, @actions/tool-cache, @octokit/core + +### Core Architecture + +``` +src/ +├── setup-uv.ts # Main entry point and orchestration +├── save-cache.ts # Post-action cache saving logic +├── update-known-versions.ts # Maintenance script for version updates +├── cache/ # Cache management functionality +├── download/ # Version resolution and binary downloading +├── utils/ # Input parsing, platform detection, configuration +└── version/ # Version resolution from various file formats +``` + +### Key Files and Locations + +- **Action Definition**: `action.yml` - Defines all inputs/outputs and entry points +- **Main Source**: `src/setup-uv.ts` - Primary action logic +- **Configuration**: `biome.json` (linting), `tsconfig.json` (TypeScript), `jest.config.js` (testing) +- **Compiled Output**: `dist/` - Contains compiled Node.js bundles (auto-generated, committed) +- **Test Fixtures**: `__tests__/fixtures/` - Sample projects for different configuration scenarios +- **Workflows**: `.github/workflows/test.yml` - Comprehensive CI/CD pipeline + +## Build and Development Process + +### Prerequisites + +- Node.js 24+ (matches GitHub Actions runtime) +- npm (included with Node.js) + +### Essential Commands (ALWAYS run in this order) + +#### 1. Install Dependencies + +```bash +npm install +``` + +**Timing**: ~20-30 seconds +**Note**: Always run this first after cloning or when package.json changes + +#### 2. Build TypeScript + +```bash +npm run build +``` + +**Timing**: ~5-10 seconds +**Purpose**: Compiles TypeScript source to JavaScript in `lib/` directory + +#### 3. Lint and Format Code + +```bash +npm run check +``` + +**Timing**: ~2-5 seconds +**Tool**: Biome (replaces ESLint/Prettier) +**Auto-fixes**: Formatting, import organization, basic linting issues + +#### 4. Package for Distribution + +```bash +npm run package +``` + +**Timing**: ~20-30 seconds +**Purpose**: Creates bundled distributions in `dist/` using @vercel/ncc +**Critical**: This step MUST be run before committing - the `dist/` files are used by GitHub Actions + +#### 5. Run Tests + +```bash +npm test +``` + +**Timing**: ~10-15 seconds +**Framework**: Jest with TypeScript support +**Coverage**: Unit tests for version resolution, input parsing, checksum validation + +#### 6. Complete Validation (Recommended) + +```bash +npm run all +``` + +**Timing**: ~60-90 seconds +**Purpose**: Runs build → check → package → test in sequence +**Use**: Before making pull requests or when unsure about build state + +### Important Build Notes + +**CRITICAL**: Always run `npm run package` after making code changes. The `dist/` directory contains the compiled bundles that GitHub Actions actually executes. Forgetting this step will cause your changes to have no effect. + +**TypeScript Warnings**: You may see ts-jest warnings about "isolatedModules" - these are harmless and don't affect functionality. + +**Biome**: This project uses Biome instead of ESLint/Prettier. Run `npm run check` to fix formatting and linting issues automatically. + +## Testing Strategy + +### Unit Tests + +- **Location**: `__tests__/` directory +- **Framework**: Jest with ts-jest transformer +- **Coverage**: Version resolution, input parsing, checksum validation, utility functions + +### Integration Tests + +- **Location**: `.github/workflows/test.yml` +- **Scope**: Full end-to-end testing across multiple platforms and scenarios +- **Key Test Categories**: + - Version installation (specific, latest, semver ranges) + - Cache behavior (setup, restore, invalidation) + - Cross-platform compatibility (Ubuntu, macOS, Windows, ARM) + - Configuration file parsing (pyproject.toml, uv.toml, requirements.txt) + - Error handling and edge cases + +### Test Fixtures + +Located in `__tests__/fixtures/`, these provide sample projects with different configurations: +- `pyproject-toml-project/` - Standard Python project with uv version specification +- `uv-toml-project/` - Project using uv.toml configuration +- `requirements-txt-project/` - Legacy requirements.txt format +- `cache-dir-defined-project/` - Custom cache directory configuration + +## Continuous Integration + +### GitHub Workflows + +#### Primary Test Suite (`.github/workflows/test.yml`) + +- **Triggers**: PRs, pushes to main, manual dispatch +- **Matrix**: Multiple OS (Ubuntu, macOS, Windows), architecture (x64, ARM), and configuration combinations +- **Duration**: ~5 minutes for full matrix +- **Key Validations**: + - Cross-platform installation and functionality + - Cache behavior and performance + - Version resolution from various sources + - Tool directory configurations + - Problem matcher functionality + +#### Maintenance Workflows + +- **CodeQL Analysis**: Security scanning on pushes/PRs +- **Update Known Versions**: Daily job to sync with latest uv releases +- **Dependabot**: Automated dependency updates + +### Pre-commit Validation + +The CI runs these checks that you should run locally: +1. `npm run all` - Complete build and test suite +2. ActionLint - GitHub Actions workflow validation +3. Change detection - Ensures no uncommitted build artifacts + +## Key Configuration Files + +### Action Configuration (`action.yml`) + +Defines 20+ inputs including version specifications, +cache settings, tool directories, and environment options. +This file is the authoritative source for understanding available action parameters. + +### TypeScript Configuration (`tsconfig.json`) + +- Target: ES2024 +- Module: nodenext (Node.js modules) +- Strict mode enabled +- Output directory: `lib/` + +### Linting Configuration (`biome.json`) + +- Formatter and linter combined +- Enforces consistent code style +- Automatically organizes imports and sorts object keys + +## Common Development Patterns + +### Making Code Changes + +1. Edit TypeScript source files in `src/` +2. Run `npm run build` to compile +3. Run `npm run check` to format and lint +4. Run `npm run package` to update distribution bundles +5. Run `npm test` to verify functionality +6. Commit all changes including `dist/` files + +### Adding New Features + +- Follow existing patterns in `src/utils/inputs.ts` for new action inputs +- Update `action.yml` to declare new inputs/outputs +- Add corresponding tests in `__tests__/` +- Add a test in `.github/workflows/test.yml` if it affects integration +- Update README.md with usage examples + +### Cache-Related Changes + +- Cache logic is complex and affects performance significantly +- Test with multiple cache scenarios (hit, miss, invalidation) +- Consider impact on both GitHub-hosted and self-hosted runners +- Validate cache key generation and dependency detection + +### Version Resolution Changes + +- Version resolution supports multiple file formats and precedence rules +- Test with fixtures in `__tests__/fixtures/` +- Consider backward compatibility with existing projects +- Validate semver and PEP 440 specification handling + +## Troubleshooting + +### Build Failures + +- **"Module not found"**: Run `npm install` to ensure dependencies are installed +- **TypeScript errors**: Check `tsconfig.json` and ensure all imports are valid +- **Test failures**: Check if test fixtures have been modified or if logic changes broke assumptions + +### Action Failures in Workflows + +- **Changes not taking effect**: Ensure `npm run package` was run and `dist/` files committed +- **Version resolution issues**: Check version specification format and file existence +- **Cache problems**: Verify cache key generation and dependency glob patterns + +### Common Gotchas + +- **Forgetting to package**: Code changes won't work without running `npm run package` +- **Platform differences**: Windows paths use backslashes, test cross-platform behavior +- **Cache invalidation**: Cache keys are sensitive to dependency file changes +- **Tool directory permissions**: Some platforms require specific directory setups + +## Trust These Instructions + +These instructions are comprehensive and current. Only search for additional information if: +- You encounter specific error messages not covered here +- You need to understand implementation details of specific functions +- The instructions appear outdated (check repository commit history) + +For most development tasks, following the build process and development patterns outlined above will be sufficient. diff --git a/.gitignore b/.gitignore index f4513f5..c2df941 100644 --- a/.gitignore +++ b/.gitignore @@ -100,3 +100,6 @@ lib/**/* # Idea IDEs (PyCharm, WebStorm, IntelliJ, etc) .idea/ + +# Compiled scripts +.github/scripts/*.js