Skip to content

Commit 2cc355c

Browse files
ArlodotexeArlodotexe
authored
Merge pull request #43 from WindowsAppCommunity/copilot/fix-42
Add comprehensive GitHub Copilot instructions for WindowsAppCommunity.Sdk
2 parents 6f00d65 + 55e1336 commit 2cc355c

File tree

1 file changed

+168
-0
lines changed

1 file changed

+168
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# WindowsAppCommunity.Sdk
2+
3+
The WindowsAppCommunity.Sdk is a .NET library for managing membership, projects, and publisher data in the Windows App Community using IPFS (InterPlanetary File System) for distributed content addressing.
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+
### Prerequisites and Setup
10+
- Install .NET 9.0 SDK:
11+
```bash
12+
curl -sSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel 9.0
13+
export PATH="$HOME/.dotnet:$PATH"
14+
```
15+
- Install IPFS Kubo (required for tests):
16+
```bash
17+
wget https://github.com/ipfs/kubo/releases/download/v0.37.0/kubo_v0.37.0_linux-amd64.tar.gz -O kubo.tar.gz
18+
tar -xzf kubo.tar.gz
19+
sudo install kubo/ipfs /usr/local/bin/
20+
```
21+
22+
### Build and Test Commands
23+
- **Bootstrap the repository:**
24+
```bash
25+
export PATH="$HOME/.dotnet:$PATH"
26+
dotnet restore
27+
```
28+
- **Build the project:**
29+
```bash
30+
dotnet build
31+
```
32+
- Build time: ~8 seconds. NEVER CANCEL - Set timeout to 60+ seconds minimum
33+
- Produces many warnings (expected in current development state)
34+
- Targets both netstandard2.0 and net9.0 frameworks
35+
36+
- **Run tests:**
37+
```bash
38+
dotnet test --verbosity normal
39+
```
40+
- **CRITICAL**: Tests require internet connectivity to dist.ipfs.tech for IPFS Kubo binary downloads
41+
- Test execution time: 1-2 minutes if network connectivity is available, immediate failure without connectivity
42+
- NEVER CANCEL: Set timeout to 30+ minutes for full test execution with network dependencies
43+
- All 16 tests will fail in network-restricted environments due to IPFS dependency downloads
44+
45+
- **Generate NuGet packages:**
46+
```bash
47+
dotnet build -c Release
48+
dotnet pack -c Release
49+
```
50+
- Creates packages in `src/bin/Release/` directory
51+
- Generates both main package and symbols package (.symbols.nupkg)
52+
53+
## Validation
54+
55+
### Build Validation
56+
- Always run `dotnet restore` before any build operations
57+
- Expect build warnings (433+ warnings are normal for current development state)
58+
- Build output should produce DLLs in `src/bin/Debug/` for both target frameworks
59+
60+
### Test Scenarios
61+
**Note**: Tests require external IPFS infrastructure connectivity and will fail in network-restricted environments.
62+
63+
When network connectivity is available, tests validate:
64+
- IPFS Kubo bootstrapping and repository creation
65+
- Project creation and management via distributed storage
66+
- Publisher and user repository operations
67+
- Image and link collection management
68+
- Cross-repository data synchronization
69+
70+
### Manual Validation Scenarios
71+
Since automated tests may fail due to network restrictions:
72+
1. **Build Verification**: Ensure `dotnet build` completes successfully
73+
2. **Package Creation**: Verify NuGet package generation in bin/Debug folders
74+
3. **API Surface**: Confirm key types are available (RepositoryContainer, Project, Publisher, User models)
75+
76+
## Common Tasks
77+
78+
### Repository Structure
79+
```
80+
WindowsAppCommunity.Sdk/
81+
├── .github/workflows/ # CI/CD pipelines
82+
│ ├── build.yml # Build validation (Ubuntu, .NET 9.0)
83+
│ └── publish.yml # Package publishing
84+
├── src/ # Main SDK source code
85+
│ ├── Models/ # Data models (Project, Publisher, User, etc.)
86+
│ ├── Nomad/ # IPFS/distributed storage implementations
87+
│ └── WindowsAppCommunity.Sdk.csproj # Main project file
88+
├── tests/ # MSTest-based test suite
89+
│ ├── BasicTests.cs # Basic repository operations
90+
│ ├── ProjectTests.cs # Project management tests
91+
│ ├── PublisherTests.cs # Publisher operations tests
92+
│ ├── UserTests.cs # User management tests
93+
│ └── TestSetupHelpers.cs # IPFS Kubo bootstrapping utilities
94+
└── WindowsAppCommunity.Sdk.sln # Solution file
95+
```
96+
97+
### Key Components
98+
- **RepositoryContainer**: Central container managing Project, Publisher, and User repositories
99+
- **Models**: Data structures for Projects, Publishers, Users with IPFS content addressing
100+
- **Nomad Layer**: IPFS-backed implementations providing distributed storage capabilities
101+
- **Test Infrastructure**: MSTest framework with IPFS Kubo integration for distributed testing
102+
103+
### Frequent Commands Reference
104+
```bash
105+
# View repository root structure
106+
ls -la
107+
108+
# Check .NET version
109+
dotnet --version
110+
111+
# Clean previous builds
112+
dotnet clean
113+
114+
# Restore packages
115+
dotnet restore
116+
117+
# Build with detailed output
118+
dotnet build --verbosity detailed
119+
120+
# Build for Release
121+
dotnet build -c Release
122+
123+
# Run specific test class
124+
dotnet test --filter "ClassName=BasicTests"
125+
126+
# Generate NuGet package (requires Release build first)
127+
dotnet build -c Release
128+
dotnet pack -c Release
129+
130+
# Check IPFS version
131+
ipfs version
132+
```
133+
134+
### Project Dependencies
135+
Key NuGet packages:
136+
- **OwlCore.Nomad.Kubo**: IPFS/Kubo integration for distributed storage
137+
- **Microsoft.Bcl.AsyncInterfaces**: Async programming support
138+
- **System.Linq.Async**: Async LINQ operations
139+
- **MSTest.TestFramework**: Testing framework
140+
141+
### Development Notes
142+
- **Early Development**: Project is version 0.0.0 and marked as "work in progress"
143+
- **Multi-Targeting**: Supports both .NET Standard 2.0 and .NET 9.0
144+
- **IPFS Dependency**: Core functionality relies on IPFS for distributed content addressing
145+
- **Network Requirements**: Full functionality requires internet connectivity for IPFS operations
146+
- **No Linting**: No specific linting configuration currently in place
147+
148+
### CI/CD Pipeline
149+
The GitHub Actions workflow (`.github/workflows/build.yml`) performs:
150+
1. .NET 9.0 SDK installation
151+
2. Repository checkout
152+
3. `dotnet build /r` (recursive build)
153+
4. `dotnet test` execution
154+
155+
### Common Issues
156+
- **Network Connectivity**: Tests fail without access to IPFS infrastructure (dist.ipfs.tech)
157+
- **.NET Version**: Requires .NET 9.0 SDK specifically (will not work with .NET 8.0 or earlier)
158+
- **IPFS Binary**: Tests automatically download IPFS Kubo binary on first run if network allows
159+
- **Long Test Times**: IPFS-based tests can take 30+ minutes when fully functional
160+
161+
### Performance Expectations
162+
- **Restore**: ~1 second
163+
- **Build (Debug)**: ~3 seconds (NEVER CANCEL - set 60+ second timeout)
164+
- **Build (Release)**: ~3 seconds (NEVER CANCEL - set 60+ second timeout)
165+
- **Test**: 1-2 minutes (failure due to network) or 30+ minutes (full execution)
166+
- **Package**: ~2-3 seconds (after Release build)
167+
168+
Always allow adequate time for operations and avoid canceling builds or tests prematurely.

0 commit comments

Comments
 (0)