Skip to content

Commit 3989833

Browse files
CopilotTheAngryByrd
Copilot
and
TheAngryByrd
authored
Add comprehensive GitHub Copilot instructions for FsToolkit.ErrorHandling development (#339)
* Initial plan * Complete comprehensive .github/copilot-instructions.md with validated build system Co-authored-by: TheAngryByrd <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: TheAngryByrd <[email protected]>
1 parent dbac90c commit 3989833

File tree

1 file changed

+178
-0
lines changed

1 file changed

+178
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# FsToolkit.ErrorHandling
2+
3+
FsToolkit.ErrorHandling is an F# utility library to work with the Result type, enabling clear, simple and powerful error handling. The library provides computation expressions, utility functions, and supports multiple target frameworks including .NET Standard 2.0/2.1, .NET 9.0, and compiles to JavaScript and Python via Fable.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
## Working Effectively
8+
9+
### Bootstrap and Build the Repository
10+
- **Install .NET SDK**: Download and install .NET 9.0.100 SDK (required for project compilation)
11+
- Also install .NET 8.0.x runtime (required for build tools)
12+
- Use `dotnet --version` to verify installation
13+
- **CRITICAL**: Ensure both SDKs are in PATH before running any build commands
14+
- **Install Node.js**: Install Node.js v18.0.0 or higher (required for Fable JavaScript builds)
15+
- Current environment has v20.19.5 which works perfectly
16+
- Use `node --version` to verify installation
17+
- **Install Python**: Install Python 3.10.0 or higher (required for Fable Python builds)
18+
- Current environment has Python 3.12.3 which works perfectly
19+
- Use `python3 --version` to verify installation
20+
21+
### Build Commands and Timing
22+
**NEVER CANCEL ANY BUILD COMMAND** - Use appropriate timeouts and wait for completion.
23+
24+
- `./build.sh DotnetRestore` -- restores .NET dependencies. Takes ~2 seconds. NEVER CANCEL.
25+
- `./build.sh Build` -- compiles all target frameworks. Takes ~90 seconds. NEVER CANCEL. Set timeout to 180+ seconds.
26+
- `./build.sh DotnetTest` -- runs F# unit tests. Takes ~12 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
27+
- `./build.sh NpmRestore` -- installs JavaScript dependencies. Takes ~11 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
28+
- `./build.sh NpmTest` -- compiles F# to JavaScript via Fable and runs tests. Takes ~50 seconds. NEVER CANCEL. Set timeout to 120+ seconds.
29+
- `./build.sh PythonTest` -- compiles F# to Python via Fable and runs tests. Takes ~2 minutes. NEVER CANCEL. Set timeout to 300+ seconds.
30+
- `./build.sh RunTests` -- runs ALL tests (F#, JavaScript, Python). Takes ~4.5 minutes. NEVER CANCEL. Set timeout to 600+ seconds.
31+
- `./build.sh FormatCode` -- formats F# code using Fantomas. Takes ~5 seconds. NEVER CANCEL.
32+
- `./build.sh CheckFormatCode` -- validates code formatting. Takes ~5 seconds. NEVER CANCEL.
33+
- `./build.sh Clean` -- cleans bin/obj folders. Takes <1 second.
34+
35+
### Default Build Target
36+
- `./build.sh` (no arguments) -- runs `DotnetPack` target which builds and packages all projects. Takes ~5-7 minutes. NEVER CANCEL. Set timeout to 600+ seconds.
37+
38+
## Validation Requirements
39+
40+
### Pre-commit Validation
41+
Always run these commands before committing changes:
42+
- `./build.sh CheckFormatCode` -- ensures code follows formatting standards
43+
- `./build.sh RunTests` -- runs complete test suite across all platforms (F#, JavaScript, Python)
44+
45+
### Complete Development Workflow Validation
46+
Test the complete workflow with: `./build.sh CheckFormatCode && ./build.sh RunTests`
47+
- Total time: ~4.5-5 minutes
48+
- Must pass all 3422+ tests across F#, JavaScript, and Python platforms
49+
- **NEVER CANCEL** - Set timeout to 600+ seconds
50+
51+
### Manual Testing Scenarios
52+
After making changes, validate functionality by:
53+
1. **Build Validation**: Run `./build.sh Build` to ensure compilation succeeds across all target frameworks
54+
2. **Test Validation**: Run `./build.sh RunTests` to execute the complete test suite (835 JS tests + 2 Python tests + 3406+ F# tests)
55+
3. **Format Validation**: Run `./build.sh CheckFormatCode` to ensure code formatting compliance
56+
57+
### CI Build Requirements
58+
The GitHub Actions CI will fail if:
59+
- Code formatting is incorrect (run `./build.sh FormatCode` to fix)
60+
- Any tests fail in F#, JavaScript, or Python targets
61+
- Build fails on any supported platform (Ubuntu, Windows, macOS)
62+
- Code analysis issues are detected
63+
64+
## Project Structure
65+
66+
### Key Directories
67+
```
68+
src/ # Source code for all packages
69+
├── FsToolkit.ErrorHandling/ # Core library (Result, AsyncResult, etc.)
70+
├── FsToolkit.ErrorHandling.AsyncSeq/ # AsyncSeq extensions
71+
├── FsToolkit.ErrorHandling.JobResult/ # JobResult extensions
72+
└── FsToolkit.ErrorHandling.IcedTasks/ # IcedTasks extensions
73+
74+
tests/ # Test projects
75+
├── FsToolkit.ErrorHandling.Tests/ # Core tests (majority of test coverage)
76+
├── FsToolkit.ErrorHandling.AsyncSeq.Tests/ # AsyncSeq tests (limited Fable support)
77+
├── FsToolkit.ErrorHandling.JobResult.Tests/ # JobResult tests
78+
└── FsToolkit.ErrorHandling.IcedTasks.Tests/ # IcedTasks tests
79+
80+
build/ # Build scripts and configuration
81+
gitbook/ # Documentation source
82+
.github/workflows/build.yml # CI/CD pipeline
83+
```
84+
85+
### Target Frameworks
86+
- **.NET Standard 2.0/2.1**: For broad compatibility
87+
- **.NET 9.0**: Latest .NET support
88+
- **Fable JavaScript**: Compiles to JavaScript for web usage
89+
- **Fable Python**: Compiles to Python for cross-platform usage (limited test coverage)
90+
91+
## Development Workflow
92+
93+
### Making Changes
94+
1. **Create feature branch**: Work on focused changes
95+
2. **Build frequently**: Run `./build.sh Build` after significant changes
96+
3. **Test early**: Run relevant test commands during development
97+
4. **Format code**: Run `./build.sh FormatCode` before committing
98+
5. **Full validation**: Run `./build.sh CheckFormatCode && ./build.sh RunTests` before PR
99+
100+
### Common Development Tasks
101+
102+
#### Adding New Functionality
103+
1. Add implementation to appropriate project in `src/`
104+
2. Add tests to corresponding test project in `tests/`
105+
3. Run `./build.sh DotnetTest` for quick F# validation
106+
4. Run `./build.sh RunTests` for full cross-platform validation
107+
108+
#### Fixing Issues
109+
1. Reproduce issue with failing test
110+
2. Implement fix in source
111+
3. Ensure tests pass: `./build.sh RunTests`
112+
4. Validate formatting: `./build.sh CheckFormatCode`
113+
114+
#### Documentation Updates
115+
- Update inline documentation in source files
116+
- Update `gitbook/` content for user-facing documentation
117+
- No separate build required for documentation changes
118+
119+
## Environment Dependencies
120+
121+
### Required SDKs and Tools
122+
- **.NET SDK 9.0.100**: Primary development SDK
123+
- **.NET Runtime 8.0.x**: Required for build tools
124+
- **Node.js 18.0.0+**: Required for Fable JavaScript compilation
125+
- **Python 3.10.0+**: Required for Fable Python compilation
126+
127+
### Package Management
128+
- **NuGet**: .NET package dependencies (automatic via `dotnet restore`)
129+
- **npm**: JavaScript dependencies for Fable builds (via `npm install`)
130+
- **Femto**: Manages Fable package compatibility (via `dotnet femto`)
131+
132+
## Troubleshooting
133+
134+
### Build Issues
135+
- **"SDK not found"**: Ensure .NET 9.0.100 SDK is installed and in PATH
136+
- **"Runtime not found"**: Install .NET 8.0.x runtime for build tools
137+
- **npm errors**: Run `npm install` manually in repository root
138+
- **Fable compilation errors**: Run `./build.sh FemtoValidate` to check package compatibility
139+
- **Security vulnerability errors (NU1902)**: Known issue with System.Security.Cryptography.Xml package in build dependencies
140+
- **TEMPORARY WORKAROUND**: Add `<NuGetAudit>false</NuGetAudit>` to build/build.fsproj PropertyGroup to bypass vulnerability check
141+
- This is a build-time dependency issue and does not affect the runtime library security
142+
- Remove the workaround once the underlying dependency is updated
143+
144+
### Test Failures
145+
- **F# test failures**: Run `./build.sh DotnetTest` to isolate .NET issues
146+
- **JavaScript test failures**: Check Node.js version (requires 18.0.0+), run `./build.sh NpmTest`
147+
- **Python test failures**: Check Python version (requires 3.10.0+), run `./build.sh PythonTest`
148+
- **Fable plugin warnings**: Ignore "Could not scan" warnings for Microsoft.TestPlatform assemblies - these are normal
149+
150+
### Format Issues
151+
- **Format check failures**: Run `./build.sh FormatCode` to auto-fix formatting
152+
- **Persistent format issues**: Check `.fantomasignore` for excluded files
153+
154+
### Performance Notes
155+
- **Fable compilation warnings**: Expect warnings about scanning TestPlatform assemblies - these are normal and don't affect functionality
156+
- **Parallel builds**: Build system uses parallel compilation (`/m:2`) to optimize performance
157+
- **Incremental builds**: Subsequent builds are faster due to incremental compilation
158+
159+
## Performance Notes
160+
161+
### Build Timing Expectations
162+
- **Quick validation** (~15s): `./build.sh DotnetTest`
163+
- **Medium validation** (~90s): `./build.sh Build`
164+
- **Full validation** (~270s): `./build.sh RunTests`
165+
- **Cross-platform CI** (~10-15 minutes): Full matrix builds across OS/versions
166+
167+
### Test Coverage Distribution
168+
- **F# Tests**: ~3406 tests (comprehensive coverage)
169+
- **JavaScript Tests**: ~835 tests (via Fable compilation)
170+
- **Python Tests**: ~2 tests (limited Fable Python support)
171+
- **Total**: 4243+ tests across all platforms
172+
173+
### Optimization Tips
174+
- Use specific targets for faster iteration during development
175+
- Run `./build.sh Build` before `RunTests` to catch compilation issues early
176+
- Use `./build.sh DotnetTest` for rapid F# validation during development
177+
- Fable compilation takes ~10 seconds for project parsing - this is normal
178+
- Python tests have minimal coverage due to Fable Python being in beta status

0 commit comments

Comments
 (0)