mirror of
https://github.com/astral-sh/setup-uv.git
synced 2025-10-18 08:37:01 +00:00
Add comprehensive Copilot instructions for setup-uv repository
Co-authored-by: eifinger <1481961+eifinger@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
225
.github/copilot-instructions.md
vendored
Normal file
225
.github/copilot-instructions.md
vendored
Normal file
@@ -0,0 +1,225 @@
|
||||
# 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**: ~20-30 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__/`
|
||||
- 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.
|
||||
16
.github/scripts/check-all-tests-passed-needs.js
vendored
Normal file
16
.github/scripts/check-all-tests-passed-needs.js
vendored
Normal file
@@ -0,0 +1,16 @@
|
||||
"use strict";
|
||||
Object.defineProperty(exports, "__esModule", { value: true });
|
||||
var fs = require("node:fs");
|
||||
var yaml = require("js-yaml");
|
||||
var workflow = yaml.load(fs.readFileSync("../workflows/test.yml", "utf8"));
|
||||
var jobs = Object.keys(workflow.jobs);
|
||||
var allTestsPassed = workflow.jobs["all-tests-passed"];
|
||||
var needs = allTestsPassed.needs || [];
|
||||
var expectedNeeds = jobs.filter(function (j) { return j !== "all-tests-passed"; });
|
||||
var missing = expectedNeeds.filter(function (j) { return !needs.includes(j); });
|
||||
if (missing.length > 0) {
|
||||
console.error("Missing jobs in all-tests-passed needs: ".concat(missing.join(", ")));
|
||||
console.info("Please add the missing jobs to the needs section of all-tests-passed in test.yml.");
|
||||
process.exit(1);
|
||||
}
|
||||
console.log("All jobs in test.yml are in the needs section of all-tests-passed.");
|
||||
Reference in New Issue
Block a user