diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 950ae4ffd81..06688710203 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,66 +1,160 @@ # GitHub Copilot Instructions for F# Compiler -## Build and test steps (only on Linux) - -Always build and test the project before submitting your final solution. - -In order to build and test, run `./build.sh -c Release --testcoreclr` . - -If the build fails with errors or non-zero exit code, fix it based on the error messages given and repeat the build step. - -If either of the steps 3 fails, fix the errors and repeat - up to 3 times. -After that, report all relevant build errors, error messages and specific details about failing tests and their test test failure details. - -### Fixing tests - -- If any of the tests fail: Check if the test, test expectation (either inline in the test or a reference file configured for the test) or implementation needs updating, and fix it -- If you see test failures for Surface area baselines: Refer to "Updating FCS surface area baselines" in devguide.md -- If you see test failures for IL baselines: Refer to "Updating ILVerify baselines" in devguide.md - - -## Acceptance criteria - -- Code is formatted using `dotnet fantomas .` executed at the repo root. -- Builds without errors. -- Runs tests without errors. If some tests needed adjustments, those test expectations/baseline adjustments were done. -- Follow the docs/release-notes folder by adding release notes. The guidelines are in docs/release-notes/About.md. -- If the acceptance criteria was not met, collect the error messages (build failures or failing tests) and report them. - -## Release notes -- Each PR must have release notes attached. Those are saved in the `docs` folder, split by version and product aspect. Follow the existing notes to figure out the right format. -- Follow the docs/release-notes structure and writing style. The guidelines are in docs/release-notes/About.md. - -## Coding standards - -### Language and Environment -- Use modern F# with functional-first approach +## STRUCTURE YOUR CHANGE (BEFORE EDITING) +Keep scope tight. +General guide: +- Use F# - Target .NET Standard 2.0 for compatibility -- Avoid external dependencies - the codebase is self-contained - -### Code Style and Standards -- Follow docs/coding-standards.md, especially: - - Prefer immutability and pure functions - - Use consistent naming (see abbreviation guide) - - Process complex types recursively with pattern matching - - Avoid single-character identifiers except in established patterns -- This project uses .fsi signature files. When adding a new public API to a namespace/module which will be consumed from other file, add it to the respective .fsi signature file as well -- Follow docs/overview.md for key compiler data formats and representations - -### Type System Handling -- When working with `TType` instances, use appropriate stripping functions: - - `stripTyparEqns` - Removes inference equations from type parameters - - `stripTyEqns` - Removes type equations and type abbreviations - - `stripTyEqnsAndErase` - Also erases compilation representations - - Match the appropriate stripper to the context (e.g., display vs compilation) - - Check equality with `typeEquiv` after stripping rather than direct comparison - -### Core Data Structures -- Use F# discriminated unions for type representations -- Respect representation hiding through access control -- Use `remapX` functions when transforming types across boundaries -- Be aware of performance implications for recursive type operations - -### Documentation and Naming -- Document public APIs with XML comments -- Use descriptive function names that indicate transformation direction -- Follow established naming conventions for error messages based on FSComp.txt file. Put all error messages into the FSComp.txt file to ensure localisation +- Avoid external dependencies – the codebase is self-contained (do NOT add new NuGet packages) +- Follow docs/coding-standards.md and docs/overview.md + +Plan your task: +1. Write a 1–2 sentence intent (bug fix / API add / language tweak). +2. Identify domain: Language (`LanguageFeature.fsi` touched) vs `src/FSharp.Core/` vs `vsintegration/` vs compiler/service. +3. Public API? Edit matching `.fsi` simultaneously. +4. New/changed diagnostics? Update FSComp.txt. +5. IL shape change expected? Plan ILVerify baseline update. +6. Expect baseline diffs? Plan `TEST_UPDATE_BSL=1` run. +7. Add/adjust tests in existing projects. +8. Decide release-notes sink now (Section 8). +9. Run formatting only at the end. + +--- + +# AFTER CHANGING CODE ( Agent-only. Ubuntu only ) + +Always run the core command. Always verify exit codes. No assumptions. + +## 1. Core Command +``` +./build.sh -c Release --testcoreclr +``` +Non‑zero → classify & stop. + +## 2. Bootstrap (Failure Detection Only) +Two-phase build. No separate bootstrap command. +Early proto/tool errors (e.g. "Error building tools") → `BootstrapFailure` (capture key lines). Stop. + +## 3. Build Failure +Proto ok but solution build fails → `BuildFailure`. +Capture exit code, ≤15 error lines (`error FS`, `error F#`, `error MSB`), binlog path: `artifacts/log/Release/Build.*.binlog`. +Do not proceed to tests. + +## 4. Tests +Core command runs CoreCLR tests: +- FSharp.Test.Utilities +- FSharp.Compiler.ComponentTests +- FSharp.Compiler.Service.Tests +- FSharp.Compiler.Private.Scripting.UnitTests +- FSharp.Build.UnitTests +- FSharp.Core.UnitTests +Failures → `TestFailure` (projects + failing lines + baseline hints). + +## 5. Baselines +Drift → update then re-run. + +General/component: +``` +TEST_UPDATE_BSL=1 +./build.sh -c Release --testcoreclr +``` +Surface area: +``` +TEST_UPDATE_BSL=1 +dotnet test tests/FSharp.Compiler.Service.Tests/FSharp.Compiler.Service.Tests.fsproj --filter "SurfaceAreaTest" -c Release /p:BUILDING_USING_DOTNET=true +``` +ILVerify: +``` +TEST_UPDATE_BSL=1 +pwsh tests/ILVerify/ilverify.ps1 +``` +Classify: `BaselineDrift(SurfaceArea|ILVerify|GeneralBSL)` + changed files. + +## 6. Formatting +``` +dotnet fantomas . --check +``` +If fail: +``` +dotnet fantomas . +dotnet fantomas . --check +``` +Still failing → `FormattingFailure`. + +## 7. Public API / IL +If new/changed public symbol (`.fsi` touched or public addition): +1. Update `.fsi`. +2. Surface area baseline flow. +3. ILVerify if IL shape changed. +4. Release notes (Section 8). +Missed baseline update → `BaselineDrift`. + +## 8. Release Notes (Sink Rules – Compact) +Most fixes → FSharp.Compiler.Service. + +| Condition | Sink | +|-----------|------| +| `LanguageFeature.fsi` changed | Language | +| Public API/behavior/perf change under `src/FSharp.Core/` | FSharp.Core | +| Only `vsintegration/` impacted | VisualStudio | +| Otherwise | FSharp.Compiler.Service | + +Action each needed sink: +- Append bullet in latest version file under `docs/release-notes//` +- Format: `* Description. ([PR #NNNNN](https://github.com/dotnet/fsharp/pull/NNNNN))` +- Optional issue link before PR. +Missing required entry → `ReleaseNotesMissing`. + +## 9. Classifications +Use one or more exactly: +- `BootstrapFailure` +- `BuildFailure` +- `TestFailure` +- `FormattingFailure` +- `BaselineDrift(SurfaceArea|ILVerify|GeneralBSL)` +- `ReleaseNotesMissing` + +Schema: +``` +Classification: +Command: +ExitCode: +KeySnippets: +ActionTaken: +Result: +OutstandingIssues: +``` + +## 10. Decision Flow +1. Format check +2. Core command +3. If fail classify & stop +4. Tests → `TestFailure` if any +5. Baseline drift? update → re-run → classify if persists +6. Public surface/IL? Section 7 +7. Release notes sink (Section 8) +8. If no unresolved classifications → success summary + +## 11. Success Example +``` +AllChecksPassed: + Formatting: OK + Bootstrap: OK + Build: OK + Tests: Passed + Baselines: Clean + ReleaseNotes: FSharp.Compiler.Service +``` + +## 12. Failure Example +``` +BootstrapFailure: + Command: ./build.sh -c Release --testcoreclr + ExitCode: 1 + KeySnippets: + - "Error building tools" + ActionTaken: None + Result: Stopped + OutstandingIssues: Bootstrap must be fixed +``` +(eof)