Skip to content

Commit 91244c9

Browse files
dvoiturondvoituron
authored
Merge branch 'dev-v5' into users/aclerbois/dev-v5/add-mcp
2 parents dc9f8bb + fc2faa7 commit 91244c9

File tree

1 file changed

+213
-0
lines changed

1 file changed

+213
-0
lines changed

‎AGENTS.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
# AGENTS.md
2+
3+
This file provides context and instructions for AI coding agents working on the **Microsoft Fluent UI Blazor** components library.
4+
5+
## Project Overview
6+
7+
This is a .NET Blazor component library that provides Fluent UI design system components for Blazor applications. The library wraps Microsoft's official **Fluent UI Web Components** and provides additional components leveraging the Fluent Design System.
8+
9+
- **Main Package**: `Microsoft.FluentUI.AspNetCore.Components`
10+
- **Target Framework**: .NET 8+
11+
- **License**: MIT
12+
- **Language**: C# with Razor components
13+
- **Documentation**: https://www.fluentui-blazor.net
14+
15+
## Repository Structure
16+
17+
```
18+
src/
19+
├── Core/ # Main component library
20+
├── Core.Scripts/ # TypeScript/JavaScript for web components
21+
└── Extensions/ # Additional packages (EF adapter, OData, etc.)
22+
23+
tests/
24+
├── Core/ # Unit tests (bUnit)
25+
└── Integration/ # Integration tests
26+
27+
examples/
28+
├── Demo/ # Demo application
29+
└── Samples/ # Sample projects
30+
```
31+
32+
## Setup Commands
33+
34+
### Prerequisites
35+
- .NET 8 SDK or later
36+
- Node.js 22.x (for Core.Scripts project)
37+
- Visual Studio 2026 (recommended on Windows)
38+
39+
### Build Commands
40+
41+
```bash
42+
# Build the entire solution
43+
dotnet build Microsoft.FluentUI-v5.sln
44+
45+
# Build only the core component library
46+
dotnet build src/Core/Microsoft.FluentUI.AspNetCore.Components.csproj
47+
48+
# Build the demo application
49+
dotnet build examples/Demo/FluentUI.Demo/FluentUI.Demo.csproj
50+
51+
# Clean the solution
52+
dotnet clean Microsoft.FluentUI-v5.sln
53+
54+
# Restore packages
55+
dotnet restore Microsoft.FluentUI-v5.sln
56+
```
57+
58+
### Run the Demo
59+
60+
```bash
61+
# Run demo application
62+
dotnet run --project examples/Demo/FluentUI.Demo/FluentUI.Demo.csproj
63+
64+
# Watch mode (hot reload)
65+
dotnet watch run --project examples/Demo/FluentUI.Demo/FluentUI.Demo.csproj
66+
```
67+
68+
## Testing Instructions
69+
70+
### Running Tests
71+
72+
```bash
73+
# Run all unit tests
74+
dotnet test tests/Core/Components.Tests.csproj
75+
76+
# Run specific test
77+
dotnet test tests/Core/Components.Tests.csproj --filter "FullyQualifiedName~TestClassName"
78+
```
79+
80+
### Unit Test Guidelines
81+
82+
- Tests use **bUnit** for Blazor component testing
83+
- Tests use **Verify** for snapshot testing
84+
- Test file naming: `{ComponentName}Tests.cs`
85+
- Test method naming: `{MethodName}_{Scenario}_{ExpectedBehavior}`
86+
- Always add or update tests when modifying components
87+
- Run all tests before submitting a PR
88+
89+
### Test File Location
90+
91+
Unit tests are in `tests/Core/Components/` mirroring the component structure in `src/Core/Components/`.
92+
93+
## Code Style Guidelines
94+
95+
### C# Conventions
96+
97+
- **Nullable**: Enabled (`<Nullable>enable</Nullable>`)
98+
- **Warnings as Errors**: Enabled (`<TreatWarningsAsErrors>true</TreatWarningsAsErrors>`)
99+
- **Code Style**: Enforced in build (`<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>`)
100+
- Use C# latest language features
101+
- Follow Microsoft C# coding conventions
102+
103+
### Component Development
104+
105+
- Components are in `src/Core/Components/`
106+
- Each component should have its own folder
107+
- Include: `.razor` file, `.razor.cs` code-behind (if needed), `.razor.css` styles (if needed)
108+
- Expose design tokens for customization
109+
- Ensure accessibility compliance
110+
111+
### Razor Component Pattern
112+
113+
```csharp
114+
// Example component structure
115+
public partial class FluentComponentName : FluentComponentBase
116+
{
117+
[Parameter]
118+
public string? Property { get; set; }
119+
120+
[Parameter]
121+
public EventCallback<T> OnEvent { get; set; }
122+
}
123+
```
124+
125+
## PR Guidelines
126+
127+
### Before Submitting
128+
129+
1. **Rebase** your branch from the target branch (do NOT use `git merge`)
130+
2. Run all unit tests: `dotnet test tests/Core/Components.Tests.csproj`
131+
3. Ensure the build passes: `dotnet build Microsoft.FluentUI-v5.sln`
132+
4. Update documentation if needed
133+
134+
### Commit Messages
135+
136+
Follow [Conventional Commits](https://www.conventionalcommits.org/):
137+
138+
- `feat:` - New feature
139+
- `fix:` - Bug fix
140+
- `docs:` - Documentation changes
141+
- `chore:` - Maintenance tasks
142+
- `refactor:` - Code refactoring
143+
- `test:` - Adding or updating tests
144+
145+
### PR Checklist
146+
147+
- [ ] Tests added/updated for changes
148+
- [ ] Changes have been tested locally
149+
- [ ] Documentation updated if needed
150+
- [ ] Follows project coding standards
151+
152+
## NPM/JavaScript Setup (Core.Scripts)
153+
154+
If you encounter NPM authentication issues (E401):
155+
156+
```bash
157+
cd src/Core.Scripts
158+
159+
# Install vsts-npm-auth
160+
npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false
161+
162+
# Get authentication token
163+
vsts-npm-auth -config .npmrc -force
164+
165+
# Install packages
166+
npm install
167+
```
168+
169+
## Important Files
170+
171+
- `Directory.Build.props` - Central versioning and build configuration
172+
- `Directory.Packages.props` - Central package version management
173+
- `.github/CODEOWNERS` - Code ownership (@vnbaaij @dvoituron)
174+
- `docs/contributing.md` - Contribution guidelines
175+
- `docs/unit-tests.md` - Detailed unit testing documentation
176+
177+
## Security Considerations
178+
179+
- Do not commit sensitive data or credentials
180+
- Review the `SECURITY.md` file for security policies
181+
- Report security vulnerabilities through proper channels (not public issues)
182+
183+
## Contributing Workflow
184+
185+
This repository uses a fork-based contribution model:
186+
187+
1. **Fork** the repository from [microsoft/fluentui-blazor](https://github.com/microsoft/fluentui-blazor)
188+
2. **Clone** your fork locally
189+
3. **Create a feature branch** from the target branch (`dev-v5`)
190+
4. **Make changes** and commit following conventional commit guidelines
191+
5. **Push** to your fork
192+
6. **Create a Pull Request** targeting the upstream repository `microsoft/fluentui-blazor`
193+
194+
### Remote Configuration
195+
196+
```bash
197+
# Add upstream remote (if not already configured)
198+
git remote add upstream https://github.com/microsoft/fluentui-blazor.git
199+
200+
# Fetch upstream changes
201+
git fetch upstream
202+
203+
# Rebase your branch on upstream
204+
git rebase upstream/dev-v5
205+
```
206+
207+
## Additional Resources
208+
209+
- [Demo Site](https://www.fluentui-blazor.net)
210+
- [Discord Community](https://discord.gg/M5cBTfp6J2)
211+
- [GitHub Issues](https://github.com/microsoft/fluentui-blazor/issues)
212+
- [Contributing Guide](docs/contributing.md)
213+
- [Unit Tests Guide](docs/unit-tests.md)

0 commit comments

Comments
 (0)