Skip to content

Commit c47c0ec

Browse files
CopilotTheAngryByrd
Copilot
and
TheAngryByrd
authored
Add comprehensive GitHub Copilot instructions for MiniScaffold development (#294)
* Initial plan * Add comprehensive GitHub Copilot instructions for MiniScaffold Co-authored-by: TheAngryByrd <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: TheAngryByrd <[email protected]>
1 parent ab9e1ed commit c47c0ec

File tree

1 file changed

+162
-0
lines changed

1 file changed

+162
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# MiniScaffold Development Instructions
2+
3+
MiniScaffold is a .NET 8.0 F# template project that generates scaffolding for F# libraries and console applications. It uses FAKE (F# Make) for build automation and includes comprehensive tooling for testing, documentation, and release management.
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+
### Essential Setup Commands
10+
Run these commands in order to bootstrap the development environment:
11+
12+
```bash
13+
# Navigate to repository root
14+
cd /home/runner/work/MiniScaffold/MiniScaffold
15+
16+
# Restore tools and build - takes ~20 seconds. NEVER CANCEL.
17+
./build.sh
18+
```
19+
20+
### Build System & Key Targets
21+
The project uses FAKE build system with these critical targets:
22+
23+
- **Default build (DotnetPack)**: `./build.sh` - Takes ~20 seconds. NEVER CANCEL. Set timeout to 60+ seconds.
24+
- **Integration Tests**: `./build.sh IntegrationTests` - Takes 30+ minutes. NEVER CANCEL. Set timeout to 60+ minutes. This is the most comprehensive test that validates template generation.
25+
- **Format Code**: `./build.sh FormatCode` - Takes ~5 seconds. Always run before committing.
26+
- **Check Formatting**: `./build.sh CheckFormatCode` - Takes ~3 seconds. Validates code style.
27+
- **Build Documentation**: `./build.sh BuildDocs` - Takes ~10 seconds. NEVER CANCEL.
28+
- **Clean**: `./build.sh Clean` - Cleans build artifacts.
29+
30+
### Template Development Workflow
31+
To test your changes to the template system:
32+
33+
```bash
34+
# 1. Build the template package (required after any template changes)
35+
./build.sh DotnetPack
36+
37+
# 2. Install the locally built template
38+
dotnet new uninstall MiniScaffold || echo "Not installed yet"
39+
dotnet new install ./dist/MiniScaffold.0.39.0.nupkg
40+
41+
# 3. Test library template generation (takes ~2 seconds)
42+
cd /tmp
43+
dotnet new mini-scaffold -n TestLib --githubUsername TestUser --outputType library
44+
45+
# 4. Test the generated template builds and works (takes ~25 seconds. NEVER CANCEL)
46+
cd TestLib
47+
./build.sh
48+
49+
# 5. Test console template generation
50+
cd /tmp
51+
dotnet new mini-scaffold -n TestConsole --githubUsername TestUser --outputType console
52+
cd TestConsole
53+
./build.sh
54+
```
55+
56+
## Validation Requirements
57+
58+
### CRITICAL: Always Validate Changes
59+
After making any changes to templates or build system:
60+
61+
1. **Build Validation**: Run `./build.sh` - must complete successfully in ~20 seconds
62+
2. **Template Generation**: Create both library and console templates as shown above
63+
3. **Generated Project Build**: Both generated templates must build successfully with `./build.sh`
64+
4. **Integration Tests**: Run `./build.sh IntegrationTests` for comprehensive validation (30+ minutes)
65+
66+
### Manual Testing Scenarios
67+
Always test these scenarios after making changes:
68+
69+
**Library Template Scenario:**
70+
1. Generate library: `dotnet new mini-scaffold -n MyLib --githubUsername TestUser`
71+
2. Build: `cd MyLib && ./build.sh` (must succeed in ~25 seconds)
72+
3. Verify output: Check that `dist/MyLib.0.1.0.nupkg` exists
73+
4. Test basic functionality: Run generated tests
74+
75+
**Console Template Scenario:**
76+
1. Generate console app: `dotnet new mini-scaffold -n MyApp --githubUsername TestUser --outputType console`
77+
2. Format code first: `cd MyApp && ./build.sh FormatCode` (console template may need formatting)
78+
3. Build: `./build.sh` (must succeed in ~30 seconds)
79+
4. Run the app: `dotnet run --project src/MyApp`
80+
81+
## Critical Requirements & Timing
82+
83+
### Build Timing Expectations
84+
- **NEVER CANCEL builds or tests** - builds may take 30+ minutes
85+
- Default build: ~20 seconds (timeout: 60+ seconds)
86+
- Integration tests: 30+ minutes (timeout: 60+ minutes)
87+
- Template generation: ~2 seconds
88+
- Generated template build: ~25 seconds (timeout: 60+ seconds)
89+
- Documentation build: ~10 seconds (timeout: 30+ seconds)
90+
- Code formatting: ~5 seconds
91+
92+
### Pre-Commit Requirements
93+
Always run these before committing changes:
94+
```bash
95+
./build.sh FormatCode # Format all code
96+
./build.sh CheckFormatCode # Verify formatting (must pass)
97+
./build.sh # Verify builds successfully
98+
```
99+
100+
## Common Tasks & File Locations
101+
102+
### Key Directories
103+
- `build/` - FAKE build scripts (build.fs is main build script)
104+
- `Content/` - Template content for generated projects
105+
- `Content/Library/` - F# library template
106+
- `Content/Console/` - F# console application template
107+
- `tests/MiniScaffold.Tests/` - Integration tests
108+
- `docsSrc/` - Documentation source files
109+
- `dist/` - Built NuGet packages (created by build)
110+
111+
### Important Files
112+
- `build.sh` / `build.cmd` - Cross-platform build entry points
113+
- `global.json` - .NET SDK version specification (8.0.100)
114+
- `Directory.Packages.props` - Central package management
115+
- `.config/dotnet-tools.json` - Local tools (fantomas, fsdocs-tool)
116+
- `MiniScaffold.csproj` - Main template project file
117+
118+
### Environment Variables
119+
- `CONFIGURATION` - Sets build configuration (Debug/Release), defaults to Debug
120+
- `CI` - Set to true in CI environments, affects build behavior
121+
122+
## Troubleshooting
123+
124+
### Common Issues
125+
- **Permission denied on build.sh**: Run `chmod +x ./build.sh`
126+
- **Template not found**: Run `dotnet new install ./dist/MiniScaffold.0.39.0.nupkg`
127+
- **Build timeout**: Increase timeout, builds can take 30+ minutes
128+
- **Integration tests fail**: Ensure you have network access for NuGet restore
129+
130+
### Build System Details
131+
- Uses .NET 8.0 SDK (specified in global.json)
132+
- FAKE build system (F# DSL for build automation)
133+
- Fantomas for code formatting
134+
- Expecto for testing
135+
- FSharp.Formatting/FSDocs for documentation
136+
137+
### Dependencies
138+
The project uses centralized package management. Key dependencies:
139+
- FAKE 6.1.3 (build system)
140+
- FSharp.Core 8.0.403
141+
- Expecto 10.2.2 (testing)
142+
- Local tools: fantomas 7.0.3, fsdocs-tool 18.1.0
143+
144+
## Quick Reference Commands
145+
146+
```bash
147+
# Essential workflow
148+
./build.sh # Build (20s)
149+
./build.sh FormatCode # Format code (5s)
150+
./build.sh IntegrationTests # Full test suite (30+ min)
151+
152+
# Template testing
153+
dotnet new install ./dist/MiniScaffold.0.39.0.nupkg
154+
dotnet new mini-scaffold -n MyLib --githubUsername User
155+
cd MyLib && ./build.sh
156+
157+
# Development
158+
./build.sh BuildDocs # Build documentation (10s)
159+
./build.sh Clean # Clean build artifacts
160+
```
161+
162+
**Remember: NEVER CANCEL long-running commands. Set appropriate timeouts and wait for completion.**

0 commit comments

Comments
 (0)