Skip to content

Commit 6837f6c

Browse files
CopilotCopilot
authored
Add comprehensive GitHub Copilot development instructions (#160)
1 parent 36e74d9 commit 6837f6c

File tree

1 file changed

+184
-0
lines changed

1 file changed

+184
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# CrestApps.OrchardCore Development Instructions
2+
3+
**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.**
4+
5+
## Project Overview
6+
7+
CrestApps.OrchardCore is a collection of open-source modules for **Orchard Core CMS**, a modular application framework built on **ASP.NET Core/.NET 9**. The repository contains AI modules, user management enhancements, content access control, and other CMS extensions.
8+
9+
## Working Effectively
10+
11+
### Prerequisites and Environment Setup
12+
13+
Install .NET 9.0 SDK first:
14+
```bash
15+
# Add Microsoft package repository (Ubuntu/Debian)
16+
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
17+
sudo dpkg -i packages-microsoft-prod.deb
18+
rm packages-microsoft-prod.deb
19+
20+
# Install .NET 9.0 SDK - TAKES 1-2 MINUTES
21+
sudo apt-get update
22+
sudo apt-get install -y dotnet-sdk-9.0
23+
24+
# Verify installation
25+
dotnet --version # Should show 9.0.x
26+
```
27+
28+
### Build Process
29+
30+
**CRITICAL BUILD LIMITATION**: The .NET build requires access to Orchard Core 3.0 preview packages from `https://nuget.cloudsmith.io/orchardcore/preview/v3/index.json`. In environments with restricted network access (like CI runners or sandboxed environments), the build will fail with network connectivity errors.
31+
32+
#### Asset Build (Always Works)
33+
```bash
34+
# Install npm dependencies - TAKES 2-3 MINUTES, NEVER CANCEL
35+
npm install
36+
37+
# Build frontend assets - TAKES 4 SECONDS
38+
npm run rebuild
39+
# OR
40+
gulp rebuild
41+
```
42+
43+
#### .NET Solution Build (Network Dependent)
44+
```bash
45+
# Full solution build - ONLY WORKS WITH NETWORK ACCESS TO CLOUDSMITH
46+
# TAKES 5-10 MINUTES when successful, NEVER CANCEL
47+
dotnet build -c Release -warnaserror /p:TreatWarningsAsErrors=true /p:RunAnalyzers=true /p:NuGetAudit=false
48+
```
49+
50+
**If build fails with NU1301 errors** about `nuget.cloudsmith.io`, this is expected in restricted environments. Document this limitation rather than attempting workarounds.
51+
52+
#### Unit Tests (Requires Successful Build)
53+
```bash
54+
# Run unit tests - TAKES 2-5 MINUTES, NEVER CANCEL
55+
dotnet test -c Release --no-build ./tests/CrestApps.OrchardCore.Tests/CrestApps.OrchardCore.Tests.csproj
56+
```
57+
58+
### Running the Application
59+
60+
**Web Application**: The main application is in `src/Startup/CrestApps.OrchardCore.Cms.Web/`
61+
62+
```bash
63+
# Run the CMS web application (requires successful build)
64+
cd src/Startup/CrestApps.OrchardCore.Cms.Web
65+
dotnet run
66+
67+
# Application runs on: http://localhost:5000
68+
# Admin setup occurs on first run
69+
```
70+
71+
### Validation Scenarios
72+
73+
**When the build succeeds**, always validate changes by:
74+
75+
1. **Build Validation**: Run both asset and .NET builds
76+
2. **Test Validation**: Execute the full test suite
77+
3. **Web Application Testing**:
78+
- Start the web application
79+
- Complete the Orchard Core setup wizard
80+
- Enable relevant CrestApps modules in the admin dashboard
81+
- Test module-specific functionality (AI chat, user management, etc.)
82+
4. **Asset Validation**: Run `npm run rebuild` and verify no asset changes are uncommitted
83+
84+
**When build fails due to network issues**:
85+
- Focus on asset-only changes using `npm run rebuild`
86+
- Document any .NET code changes for testing in environments with network access
87+
- Use static analysis and code review for .NET validation
88+
89+
## Repository Structure and Navigation
90+
91+
### Key Directories
92+
```
93+
src/
94+
├── Modules/ # All CrestApps modules
95+
│ ├── CrestApps.OrchardCore.AI/ # AI core services
96+
│ ├── CrestApps.OrchardCore.AI.Chat/ # AI chat interface
97+
│ ├── CrestApps.OrchardCore.AI.Agent/ # AI agents
98+
│ ├── CrestApps.OrchardCore.AI.Mcp/ # Model Context Protocol
99+
│ ├── CrestApps.OrchardCore.OpenAI/ # OpenAI integration
100+
│ ├── CrestApps.OrchardCore.OpenAI.Azure/ # Azure OpenAI
101+
│ ├── CrestApps.OrchardCore.Ollama/ # Ollama integration
102+
│ ├── CrestApps.OrchardCore.Users/ # Enhanced user management
103+
│ ├── CrestApps.OrchardCore.Roles/ # Enhanced roles
104+
│ ├── CrestApps.OrchardCore.ContentAccessControl/ # Content permissions
105+
│ ├── CrestApps.OrchardCore.SignalR/ # SignalR integration
106+
│ └── CrestApps.OrchardCore.Resources/ # Shared resources
107+
├── Core/ # Core libraries
108+
├── Abstractions/ # Interface definitions
109+
├── Startup/ # Web applications
110+
│ └── CrestApps.OrchardCore.Cms.Web/ # Main CMS web app
111+
└── Targets/ # Package bundles
112+
113+
tests/
114+
└── CrestApps.OrchardCore.Tests/ # Unit test project
115+
116+
.github/workflows/ # CI/CD pipelines
117+
```
118+
119+
### Important Files
120+
- `CrestApps.OrchardCore.sln` - Main solution file
121+
- `global.json` - .NET SDK version (9.0.100)
122+
- `Directory.Build.props` - Common MSBuild properties
123+
- `NuGet.config` - Package source configuration (includes CloudSmith feed)
124+
- `package.json` - npm dependencies and scripts
125+
- `gulpfile.js` - Asset build configuration
126+
127+
## Common Development Tasks
128+
129+
### Adding a New Module
130+
1. Create new folder in `src/Modules/CrestApps.OrchardCore.{ModuleName}/`
131+
2. Add module project file following existing patterns
132+
3. Include `Manifest.cs` with module definition
133+
4. Add module reference to appropriate target package
134+
135+
### Working with AI Modules
136+
- **Base AI Module**: `CrestApps.OrchardCore.AI` - start here for AI-related changes
137+
- **Chat Interface**: `CrestApps.OrchardCore.AI.Chat` - UI and chat functionality
138+
- **Integrations**: Specific provider modules (OpenAI, Azure, Ollama)
139+
140+
### Frontend Development
141+
- CSS/SCSS files are in individual module directories
142+
- TypeScript/JavaScript files are built using gulp pipeline
143+
- Run `npm run rebuild` after any frontend changes
144+
- Use `npm run watch` for development with auto-rebuild
145+
146+
### Testing Workflow
147+
1. Make code changes
148+
2. Run `npm run rebuild` for frontend changes
149+
3. Run `dotnet build` for backend changes (if network allows)
150+
4. Run `dotnet test` for unit tests (if build succeeds)
151+
5. Start web application and test manually
152+
153+
## Troubleshooting
154+
155+
### Build Issues
156+
- **NU1301 errors**: Network connectivity to CloudSmith required, expected in restricted environments
157+
- **SDK version errors**: Ensure .NET 9.0.100+ is installed via `dotnet --version`
158+
- **npm install failures**: Node.js 15+ required (check with `node --version`)
159+
160+
### Runtime Issues
161+
- **Database**: Uses SQLite by default, no external DB required for development
162+
- **Modules not appearing**: Enable modules in Orchard Core admin dashboard
163+
- **Permission errors**: Check content access control module configuration
164+
165+
### Network Dependencies
166+
This project requires network access to:
167+
- `https://api.nuget.org/v3/index.json` (public NuGet)
168+
- `https://nuget.cloudsmith.io/orchardcore/preview/v3/index.json` (Orchard Core previews)
169+
170+
If CloudSmith is inaccessible, only asset builds and code analysis are possible.
171+
172+
## CI/CD Integration
173+
174+
Before committing:
175+
1. Run `npm run rebuild` - asset build must complete cleanly
176+
2. Run `dotnet build` (if network allows) - solution must build without warnings
177+
3. Run `dotnet test` (if build succeeds) - all tests must pass
178+
4. Verify no uncommitted asset changes with `git status`
179+
180+
The CI pipeline validates builds on both Ubuntu and Windows, so test locally on similar environments when possible.
181+
182+
---
183+
184+
**Remember: Always build and validate your changes thoroughly. The modular architecture means changes can affect multiple modules, so comprehensive testing is essential.**

0 commit comments

Comments
 (0)