Add comprehensive Copilot coding agent instructions for repository onboarding (#6920)
* Initial plan * Add comprehensive .github/copilot-instructions.md with validated build instructions Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com>
This commit is contained in:
Copilot
GitHub
parent
67fb43e0ba
commit
54c8a010fe
230
.github/copilot-instructions.md
vendored
Normal file
230
.github/copilot-instructions.md
vendored
Normal file
|
|
@ -0,0 +1,230 @@
|
|||
# Copilot Coding Agent Instructions for Elsa Workflows
|
||||
|
||||
## Repository Overview
|
||||
|
||||
**Elsa Workflows** is a powerful .NET workflow library that enables workflow execution within any .NET application. This is version 3.0, supporting .NET 9.0 and providing both a visual designer and programmatic workflow definition capabilities.
|
||||
|
||||
### Key Statistics
|
||||
- **Language**: C# (.NET 9.0)
|
||||
- **Architecture**: Modular library with 104+ projects
|
||||
- **Code Size**: ~3,500 C# files across modules
|
||||
- **License**: MIT
|
||||
- **Build System**: NUKE build automation
|
||||
- **Target Frameworks**: .NET 9.0 (primary)
|
||||
|
||||
## High-Level Architecture
|
||||
|
||||
### Directory Structure
|
||||
```
|
||||
src/
|
||||
├── apps/ # Reference applications (5 projects)
|
||||
│ ├── Elsa.Server.Web # Workflow server only
|
||||
│ ├── Elsa.ServerAndStudio.Web # Combined server + studio
|
||||
│ ├── Elsa.Studio.Web # Studio web interface
|
||||
│ ├── ElsaStudioWebAssembly # Studio WebAssembly app
|
||||
│ └── Elsa.Server.LoadBalancer # Load balancer
|
||||
├── common/ # Shared libraries (8 projects)
|
||||
├── modules/ # Core functionality modules (70+ projects)
|
||||
│ ├── Elsa.Workflows.Core # Core workflow engine
|
||||
│ ├── Elsa.Workflows.Runtime # Runtime execution
|
||||
│ ├── Elsa.Workflows.Api # REST API
|
||||
│ ├── Elsa.Http # HTTP activities
|
||||
│ ├── Elsa.Email # Email activities
|
||||
│ └── [many others] # Database, messaging, etc.
|
||||
└── clients/ # API clients
|
||||
test/
|
||||
├── unit/ # Unit tests
|
||||
├── integration/ # Integration tests
|
||||
├── component/ # Component tests
|
||||
└── performance/ # Performance tests
|
||||
build/ # NUKE build configuration
|
||||
docker/ # Docker configurations
|
||||
```
|
||||
|
||||
### Core Components
|
||||
- **Elsa.Workflows.Core**: Main workflow engine and activities
|
||||
- **Elsa.Workflows.Runtime**: Workflow execution runtime
|
||||
- **Elsa.Workflows.Api**: RESTful API for workflow management
|
||||
- **Elsa.Workflows.Management**: Workflow definition management
|
||||
- **Elsa modules**: Specialized functionality (HTTP, email, scheduling, etc.)
|
||||
|
||||
## Build Instructions
|
||||
|
||||
### Prerequisites
|
||||
- **.NET 9.0 SDK** (verified working version: 9.0.305)
|
||||
- **Build time**: Initial restore ~1-2 minutes, full compile ~5-10 minutes
|
||||
|
||||
### Critical Build Information
|
||||
|
||||
⚠️ **IMPORTANT**: The repository has external dependencies that may cause build failures:
|
||||
|
||||
1. **External NuGet Feeds**: Some projects depend on packages from:
|
||||
- `https://f.feedz.io/elsa-workflows/elsa-3/nuget/index.json` (Elsa Studio packages)
|
||||
- `https://f.feedz.io/sfmskywalker/webhooks-core/nuget/index.json` (Webhooks packages)
|
||||
|
||||
2. **Build Failure Workarounds**:
|
||||
- Studio apps (`Elsa.Studio.Web`, `ElsaStudioWebAssembly`, `Elsa.ServerAndStudio.Web`) depend on prebuilt studio packages that may not be accessible
|
||||
- Server app (`Elsa.Server.Web`) depends on WebhooksCore package that may not be accessible
|
||||
- Core workflow functionality can be built independently
|
||||
- Some test projects may fail due to missing external packages
|
||||
|
||||
### Build Commands
|
||||
|
||||
**Primary build script**: `./build.sh` (Linux/macOS) or `.\build.cmd` (Windows)
|
||||
|
||||
```bash
|
||||
# View available targets
|
||||
./build.sh --help
|
||||
|
||||
# Clean build artifacts
|
||||
./build.sh Clean
|
||||
|
||||
# Restore packages (may show warnings for inaccessible feeds)
|
||||
./build.sh Restore --ignore-failed-sources
|
||||
|
||||
# Compile core components (excludes studio apps)
|
||||
./build.sh Compile
|
||||
|
||||
# Run tests (limited due to external dependencies)
|
||||
./build.sh Test
|
||||
|
||||
# Create NuGet packages
|
||||
./build.sh Pack
|
||||
|
||||
# Full CI pipeline (compile, test, pack)
|
||||
./build.sh Compile Test Pack
|
||||
```
|
||||
|
||||
**Direct dotnet commands** for core components:
|
||||
```bash
|
||||
# Build specific core projects that don't require external packages
|
||||
dotnet restore src/modules/Elsa.Workflows.Core/ --ignore-failed-sources
|
||||
dotnet build src/modules/Elsa.Workflows.Core/ --no-restore
|
||||
dotnet restore src/modules/Elsa.Workflows.Runtime/ --ignore-failed-sources
|
||||
dotnet build src/modules/Elsa.Workflows.Runtime/ --no-restore
|
||||
|
||||
# Note: Server apps may fail due to WebhooksCore dependency
|
||||
# Build and test individual core modules
|
||||
find test/unit -name "*.csproj" | head -5 | xargs -I {} dotnet build {}
|
||||
```
|
||||
|
||||
### Expected Build Warnings
|
||||
- `NU1900`: Unable to load service index for external feeds (safe to ignore)
|
||||
- `NU1801`: Service index warnings for feedz.io sources (safe to ignore)
|
||||
- `NU1101`: Missing Elsa.Studio packages (blocks studio app builds)
|
||||
|
||||
### Successful Build Indicators
|
||||
- Core modules (Elsa.Workflows.Core, etc.) compile successfully
|
||||
- Server applications (Elsa.Server.Web) build without the studio UI
|
||||
- Most modules show "succeeded with X warning(s)" (warnings are acceptable)
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Structure
|
||||
- **Unit tests**: `test/unit/` - Fast, isolated tests
|
||||
- **Integration tests**: `test/integration/` - End-to-end scenarios
|
||||
- **Component tests**: `test/component/` - Feature testing
|
||||
- **Performance tests**: `test/performance/` - Benchmarks
|
||||
|
||||
### Running Tests
|
||||
```bash
|
||||
# Via NUKE build system
|
||||
./build.sh Test
|
||||
|
||||
# Direct dotnet test (for accessible projects)
|
||||
dotnet test test/unit/[specific-project]/
|
||||
dotnet test --no-build --no-restore [project-path]
|
||||
```
|
||||
|
||||
**Note**: Many tests may fail to run due to external package dependencies. Focus on core workflow engine tests that don't require studio packages.
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Code Standards
|
||||
- **Language version**: C# latest
|
||||
- **Target framework**: .NET 9.0
|
||||
- **Nullable reference types**: Enabled
|
||||
- **Implicit usings**: Enabled
|
||||
- **EditorConfig**: Configured (4-space indentation, CRLF line endings)
|
||||
|
||||
### Architecture Patterns
|
||||
- **Modular design**: Each feature area is a separate project/module
|
||||
- **Dependency injection**: Heavy use of Microsoft.Extensions.DependencyInjection
|
||||
- **Activity-based**: Workflows are built from composable activities
|
||||
- **Async/await**: Extensive use throughout for scalability
|
||||
|
||||
### Common Gotchas
|
||||
1. **External Dependencies**: Studio-related projects require external packages
|
||||
2. **NuGet Source Mapping**: Configured in NuGet.Config, restricts where packages can be sourced
|
||||
3. **Multiple Target Frameworks**: Some projects conditionally target different frameworks
|
||||
4. **Build Warnings**: Many NU1900/NU1801 warnings are expected and safe
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
### GitHub Actions Workflow
|
||||
- **Trigger**: Pull requests to `main` branch
|
||||
- **Runner**: ubuntu-latest
|
||||
- **.NET Version**: 9.x (latest)
|
||||
- **Commands**: `./build.cmd Compile Test Pack`
|
||||
- **File**: `.github/workflows/pr.yml` (auto-generated by NUKE)
|
||||
|
||||
### CI Pipeline Steps
|
||||
1. Checkout code
|
||||
2. Setup .NET 9.x SDK
|
||||
3. Execute: Compile → Test → Pack
|
||||
4. Expected warnings for external feed access
|
||||
5. Studio apps may be excluded from CI builds
|
||||
|
||||
## Key Configuration Files
|
||||
|
||||
- **Build**: `build/Build.cs` (NUKE build configuration)
|
||||
- **Dependencies**: `Directory.Packages.props` (central package management)
|
||||
- **Global settings**: `Directory.Build.props`
|
||||
- **NuGet**: `NuGet.Config` (package sources and mapping)
|
||||
- **Solution**: `Elsa.sln` (119 projects)
|
||||
- **Docker**: `docker/` directory with multiple Dockerfiles
|
||||
- **GitHub Actions**: `.github/workflows/` (auto-generated)
|
||||
|
||||
## Docker Support
|
||||
|
||||
Multiple Docker configurations available:
|
||||
- `ElsaServer.Dockerfile` - Server only
|
||||
- `ElsaServerAndStudio.Dockerfile` - Combined server + studio
|
||||
- `ElsaStudio.Dockerfile` - Studio only
|
||||
- Docker Compose configurations for development
|
||||
|
||||
## Quick Start for Development
|
||||
|
||||
1. **Clone and build core components**:
|
||||
```bash
|
||||
git clone [repo-url]
|
||||
cd elsa-core
|
||||
./build.sh Clean Restore --ignore-failed-sources
|
||||
```
|
||||
|
||||
2. **Work with core modules** (avoid studio dependencies):
|
||||
```bash
|
||||
cd src/modules/Elsa.Workflows.Core
|
||||
dotnet build
|
||||
dotnet test ../../test/unit/[related-tests]/
|
||||
```
|
||||
|
||||
3. **Work with core modules that don't require external dependencies**:
|
||||
```bash
|
||||
cd src/modules/Elsa.Workflows.Core
|
||||
dotnet restore --ignore-failed-sources
|
||||
dotnet build --no-restore
|
||||
```
|
||||
|
||||
## Important Notes for Coding Agents
|
||||
|
||||
1. **Always use `--ignore-failed-sources`** when restoring packages
|
||||
2. **Focus on core workflow functionality** rather than studio UI components
|
||||
3. **Studio apps require external packages** that may not be accessible
|
||||
4. **Build warnings are normal** - don't try to fix NU1900/NU1801 warnings
|
||||
5. **Test individual modules** rather than solution-wide tests when external deps fail
|
||||
6. **Use direct dotnet commands** for building specific components when NUKE fails
|
||||
7. **Check project references** before attempting builds - some projects have conditional references
|
||||
8. **Start with core modules** like `Elsa.Workflows.Core`, `Elsa.Workflows.Runtime` which are more likely to build successfully
|
||||
|
||||
Trust these instructions for build and development workflows. Only search for additional information if these instructions are incomplete or found to be incorrect.
|
||||
Loading…
Reference in a new issue