Skip to content

Commit ecec281

Browse files
CopilotrojiAndriySvyryd
authored
Add .github/copilot-instructions.md for agent onboarding (#5216)
Co-authored-by: roji <1862641+roji@users.noreply.github.com> Co-authored-by: AndriySvyryd <6539701+AndriySvyryd@users.noreply.github.com>
1 parent 36e1f85 commit ecec281

1 file changed

Lines changed: 153 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Copilot Instructions for EntityFramework.Docs
2+
3+
## Repository Overview
4+
5+
This repository contains the **Entity Framework Core (EF Core) and Entity Framework 6 (EF6) documentation** published at <https://learn.microsoft.com/ef/>. It is a **documentation-focused repository** with markdown documentation files and C# code samples.
6+
7+
**Key Technologies:**
8+
- **Documentation**: Markdown, DocFX, Microsoft Learn publishing platform
9+
- **Samples**: Latest public release of .NET, C#, Entity Framework Core/EF6, SQL Server, SQLite, Cosmos DB
10+
11+
## Critical Build & Validation Instructions
12+
13+
### Prerequisites
14+
- **.NET SDK** (latest public release) is required (check with `dotnet --version`)
15+
- **Node.js** for markdown linting (check with `node --version`)
16+
17+
### Markdown Linting (ALWAYS RUN BEFORE COMMITTING)
18+
19+
**Command:**
20+
```bash
21+
npm i -g markdownlint-cli
22+
markdownlint "**/*.md" -i "entity-framework/ef6/"
23+
```
24+
25+
**Configuration:** `.markdownlint.json` at repo root
26+
**Key Rules:** MD046 (fenced code blocks), MD025 (single H1 with front matter)
27+
**CI Workflow:** `.github/workflows/markdownlint.yml` runs on all PRs with markdown changes
28+
**IMPORTANT:** EF6 documentation (`entity-framework/ef6/`) is excluded from linting
29+
30+
### Building Code Samples
31+
32+
**Location:** All samples are in `samples/` directory
33+
- `samples/core/` - EF Core samples
34+
- `samples/end2end/PlanetaryDocs/` - Complete end-to-end Blazor application
35+
36+
Samples are standard .NET projects. Build them with:
37+
```bash
38+
cd samples/end2end/PlanetaryDocs
39+
dotnet build
40+
```
41+
42+
Or build all core samples:
43+
```bash
44+
cd samples/core
45+
dotnet build
46+
```
47+
48+
**CI Workflow:** `.github/workflows/build-samples.yml` runs on PRs to `live` branch with changes to `samples/`
49+
50+
## Repository Structure
51+
52+
### Documentation
53+
```
54+
entity-framework/
55+
├── docfx.json # DocFX configuration
56+
├── core/ # EF Core documentation
57+
├── ef6/ # EF6 documentation (excluded from markdownlint)
58+
├── efcore-and-ef6/ # Comparison and porting guides
59+
└── breadcrumb/ # Navigation breadcrumbs
60+
```
61+
62+
### Configuration Files
63+
- `.markdownlint.json` - Markdown linting rules
64+
- `.openpublishing.publish.config.json` - Microsoft Learn publishing config
65+
- `.openpublishing.redirection.json` - URL redirections (update when renaming/moving files)
66+
- `.github/workflows/markdownlint.yml` - Markdown lint CI
67+
- `.github/workflows/build-samples.yml` - Sample build CI
68+
69+
### Samples
70+
```
71+
samples/
72+
├── core/ # EF Core samples
73+
│ ├── Samples.sln # Solution with all core samples
74+
│ └── .editorconfig # Code style rules
75+
└── end2end/
76+
└── PlanetaryDocs/ # Complete Blazor app
77+
```
78+
79+
## Making Changes
80+
81+
### Documentation Changes
82+
83+
**File Format:** DocFX-flavored Markdown (DFM), superset of GitHub-flavored Markdown (GFM)
84+
**Style Guide:** <https://learn.microsoft.com/contribute/dotnet/dotnet-style-guide>
85+
86+
**Code Snippet Syntax:**
87+
- Reference external code files (preferred): `[!code-csharp[Main](../../../samples/core/saving/Program.cs)]`
88+
- With C# region (always prefer over line ranges): `[!code-csharp[Main](../../../samples/core/saving/Program.cs?name=snippet_Example)]`
89+
- With highlighting: `[!code-csharp[Main](../../../samples/core/saving/Program.cs?highlight=1-3,10)]`
90+
91+
**Static Content:** Images and files in `_static/` folders within each documentation area
92+
93+
**ALWAYS:**
94+
1. Ensure code snippets reference actual sample files in `samples/` directory
95+
2. Run `markdownlint "**/*.md" -i "entity-framework/ef6/"` before committing
96+
3. Match folder structure: docs in `entity-framework/core/` align with samples in `samples/core/`
97+
4. When referencing an API, use docfx `<xref>` rather than code fencing to link to the API documentation
98+
5. When adding, removing or renaming pages, update the `entity-framework/toc.yml` file to make the changes appear in the doc site's table of contents
99+
6. If renaming or moving files, update `.openpublishing.redirection.json` to add redirects from old URLs
100+
101+
### Sample Code Changes
102+
103+
**ALWAYS:**
104+
1. Ensure samples build successfully: `cd samples/end2end/PlanetaryDocs && dotnet build`
105+
2. Follow existing code style (see `samples/core/.editorconfig`)
106+
3. Use C# regions (`#region snippet_Name`) for code referenced in documentation
107+
4. When editing samples, verify that documentation referencing those samples still uses correct line numbers for highlighting
108+
109+
**Common Sample Patterns:**
110+
- Console applications showing specific EF Core features
111+
- Each sample folder typically has one `.csproj` file
112+
- Samples use in-memory SQLite or SQL Server LocalDB
113+
114+
## Testing Documentation Locally with DocFX
115+
116+
**DocFX** creates a locally hosted version of the documentation site (without Microsoft Learn styling).
117+
118+
**Requirements:**
119+
- Windows: .NET Framework + DocFX tool
120+
- macOS/Linux: Mono + DocFX
121+
122+
**Commands (not regularly used for PRs):**
123+
```bash
124+
# Download DocFX from https://github.com/dotnet/docfx/releases
125+
# Add to PATH, then from repo root:
126+
docfx entity-framework/docfx.json -t default --serve
127+
# View at http://localhost:8080
128+
```
129+
130+
**Note:** DocFX is optional for most contributions. Focus on markdown linting and sample builds.
131+
132+
## Common Pitfalls & Solutions
133+
134+
**Problem:** `samples/core/Samples.sln` build fails with "Resource temporarily unavailable" NuGet errors
135+
**Solution:** This is a transient network issue with Azure DevOps preview package feeds. Retry the build. If persistent, build individual sample projects instead of the full solution.
136+
137+
**Problem:** Markdownlint errors on legitimate markdown
138+
**Solution:** Check `.markdownlint.json` for disabled rules. Some rules (MD028, MD033, MD036, MD041) are intentionally disabled for documentation needs.
139+
140+
**Problem:** Code snippet not rendering in documentation
141+
**Solution:** Verify the referenced file path is correct relative to the .md file location. Ensure C# region names match exactly (case-sensitive).
142+
143+
**Problem:** Changes to EF6 docs trigger linting warnings
144+
**Solution:** EF6 docs (`entity-framework/ef6/`) are excluded from linting. This is intentional due to legacy content.
145+
146+
## Trust These Instructions
147+
148+
These instructions have been validated by running actual builds, tests, and linting on the repository. Only perform additional exploration if:
149+
- Information is incomplete or unclear
150+
- Instructions are found to be incorrect
151+
- You need details about a specific undocumented area
152+
153+
For quick fixes (typos, grammar), simple markdown edits without building samples are acceptable.

0 commit comments

Comments
 (0)