Skip to content

Commit 685f7cf

Browse files
w-ahmadw-ahmad
authored
Merge pull request #238 from w-ahmad/copilot/set-up-copilot-instructions
Add GitHub Copilot instructions for repository
2 parents 69cbc24 + bf48516 commit 685f7cf

1 file changed

Lines changed: 265 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
# GitHub Copilot Instructions for WinUI.TableView
2+
3+
## Project Overview
4+
5+
**WinUI.TableView** is a lightweight and fast data grid control for WinUI 3 apps with support for the Uno Platform. It's derived from `ListView` and provides an Excel-like data table experience with features like column filtering, sorting, editing, and data export.
6+
7+
- **Repository**: https://github.com/w-ahmad/WinUI.TableView
8+
- **Documentation**: https://w-ahmad.github.io/WinUI.TableView/
9+
- **NuGet Package**: WinUI.TableView
10+
- **License**: MIT
11+
12+
## Technology Stack
13+
14+
- **Primary Platform**: WinUI 3 (Windows App SDK)
15+
- **Cross-Platform Support**: Uno Platform (WASM, Desktop)
16+
- **Target Frameworks**:
17+
- .NET 8.0 and .NET 9.0 (Uno Platform targets)
18+
- .NET 8.0-windows10.0.19041.0 and .NET 9.0-windows10.0.19041.0 (WinUI 3 targets)
19+
- **Languages**: C# with XAML
20+
- **Dependencies**:
21+
- Microsoft.WindowsAppSDK (for WinUI targets)
22+
- Uno.WinUI (for non-Windows targets)
23+
- CommunityToolkit.WinUI.Behaviors
24+
25+
## Repository Structure
26+
27+
```
28+
/
29+
├── src/ # Main library source code
30+
│ ├── Columns/ # Column type implementations
31+
│ ├── Controls/ # Custom control implementations
32+
│ ├── Converters/ # XAML value converters
33+
│ ├── EventArgs/ # Custom event argument classes
34+
│ ├── Extensions/ # Extension methods
35+
│ ├── Helpers/ # Helper classes and utilities
36+
│ ├── ItemsSource/ # Data source handling
37+
│ ├── Primitives/ # Base/primitive control classes
38+
│ ├── Strings/ # Localization resources
39+
│ ├── Themes/ # XAML styles and control templates
40+
│ ├── TableView.cs # Main TableView control
41+
│ └── WinUI.TableView.csproj # Project file
42+
├── tests/ # Unit tests
43+
│ └── WinUI.TableView.Tests.csproj
44+
├── docs/ # Documentation (DocFX)
45+
├── .github/ # GitHub configuration
46+
│ ├── workflows/ # CI/CD workflows
47+
│ └── ISSUE_TEMPLATE/ # Issue templates
48+
├── README.md # Project readme
49+
├── CONTRIBUTING.md # Contribution guidelines
50+
└── WinUI.TableView.slnx # Solution file
51+
```
52+
53+
## Build and Test Instructions
54+
55+
### Building the Project
56+
57+
**Prerequisites**:
58+
- Visual Studio 2022 or later
59+
- Windows 10 SDK (10.0.19041.0 or later)
60+
- .NET 8.0 and/or .NET 9.0 SDK
61+
62+
**Build Command**:
63+
```bash
64+
msbuild /restore /t:Build,Pack src/WinUI.TableView.csproj /p:Configuration=Release
65+
```
66+
67+
**Build Outputs**:
68+
- NuGet packages: `artifacts/NuGet/Release/`
69+
- Documentation is built automatically on commits to docs/ folder
70+
71+
### Running Tests
72+
73+
**Build Tests**:
74+
```bash
75+
msbuild /restore /t:Build tests/WinUI.TableView.Tests.csproj /p:Platform=x64 /p:Configuration=Release /p:OutputPath=build
76+
```
77+
78+
**Run Tests**:
79+
```bash
80+
vstest.console.exe tests\build\WinUI.TableView.Tests.build.appxrecipe --logger:"console;verbosity=normal" /InIsolation
81+
```
82+
83+
**Note**: Tests are WinUI 3 app tests and require Windows with visual UI. They run on x64 platform only.
84+
85+
## Coding Standards and Conventions
86+
87+
### Code Style
88+
89+
This project uses `.editorconfig` for consistent code formatting. Key conventions:
90+
91+
- **Indentation**: 4 spaces
92+
- **Line Endings**: CRLF (Windows style)
93+
- **Namespace Style**: File-scoped namespaces preferred
94+
- **Nullable Reference Types**: Enabled (`<Nullable>enable</Nullable>`)
95+
- **Private Fields**: Use underscore prefix (e.g., `_fieldName`)
96+
- **Interfaces**: Prefix with `I` (e.g., `ITableViewColumn`)
97+
- **Naming**: PascalCase for public members, camelCase with underscore for private fields
98+
- **Using Directives**: Place outside namespace, no separation of System directives
99+
- **File Header**: Not required
100+
101+
### XML Documentation
102+
103+
- **All public types and members must have XML documentation comments** (enforced as error via CS1591)
104+
- Use `<summary>`, `<param>`, `<returns>`, and other standard XML doc tags
105+
- Generate documentation file is enabled for the library project
106+
107+
### Platform-Specific Code
108+
109+
The project supports both WinUI 3 and Uno Platform. When writing platform-specific code:
110+
111+
- Use conditional compilation based on target framework
112+
- WinUI-specific code: Use `#if WINDOWS` or check `$([MSBuild]::GetTargetPlatformIdentifier($(TargetFramework))) == 'windows'`
113+
- Uno Platform specific: Check for non-Windows targets
114+
- Test changes on both WinUI 3 and Uno Platform targets when possible
115+
116+
### XAML Conventions
117+
118+
- Use WinUI 3 XAML syntax
119+
- Control templates and styles are in `src/Themes/` folder
120+
- Generic.xaml serves as the main resource dictionary
121+
- Use resource keys for reusable styles and templates
122+
123+
## Key Features and Components
124+
125+
### Core Components
126+
127+
1. **TableView**: Main control derived from ListView
128+
2. **TableViewColumn Types**:
129+
- TableViewTextColumn
130+
- TableViewCheckBoxColumn
131+
- TableViewComboBoxColumn
132+
- TableViewNumberColumn
133+
- TableViewToggleSwitchColumn
134+
- TableViewTemplateColumn
135+
- TableViewTimeColumn
136+
- TableViewDateColumn
137+
138+
3. **Supporting Classes**:
139+
- TableViewCell: Individual cell control
140+
- TableViewRow: Row container
141+
- TableViewColumnHeader: Column header with filtering
142+
- TableViewHeaderRow: Header row container
143+
- TableViewColumnsCollection: Column collection management
144+
145+
### Important Features
146+
147+
- Auto-generating columns from data source
148+
- Individual cell selection and editing
149+
- Excel-like column filtering
150+
- Built-in sorting
151+
- Copy to clipboard functionality
152+
- CSV export
153+
- Grid lines customization
154+
- Row details support
155+
- Localization support
156+
- Alternate row colors
157+
158+
## Common Development Tasks
159+
160+
### Adding a New Column Type
161+
162+
1. Create a new class in `src/Columns/` inheriting from `TableViewBoundColumn` or `TableViewColumn`
163+
2. Implement required abstract members
164+
3. Add XAML style if needed in `src/Themes/`
165+
4. Update documentation
166+
5. Add unit tests if applicable
167+
168+
### Adding New Features
169+
170+
1. Check existing issues and discussions first
171+
2. Start a discussion or open an issue to describe the feature
172+
3. Implement the feature with minimal changes
173+
4. Ensure compatibility with both WinUI 3 and Uno Platform
174+
5. Add XML documentation
175+
6. Update README.md and docs/ if needed
176+
7. Add unit tests where feasible
177+
8. Test on both platforms
178+
179+
### Modifying Existing Code
180+
181+
- Make surgical, minimal changes
182+
- Preserve existing behavior unless fixing a bug
183+
- Update XML documentation if changing public API
184+
- Run tests before submitting PR
185+
- Follow the existing code style
186+
187+
## Testing Guidelines
188+
189+
- Unit tests are located in `tests/` folder
190+
- Tests use MSTest framework
191+
- Focus on testing extension methods and collection operations
192+
- UI testing is limited due to WinUI 3 constraints
193+
- Test coverage includes:
194+
- Extension methods (CollectionExtensions, DateTimeExtensions, etc.)
195+
- Type utilities
196+
- Collection operations
197+
198+
## Pull Request Guidelines
199+
200+
From CONTRIBUTING.md:
201+
202+
- **Do NOT** open pull requests from your `main` branch
203+
- Always create a new feature branch (e.g., `add-feature-name`)
204+
- Test changes with both WinUI 3 and Uno Platform targets
205+
- Add or update unit tests to cover changes
206+
- Complete the PR checklist
207+
- Update documentation as needed
208+
- Ensure CI build passes
209+
210+
## Localization
211+
212+
- Localized strings are in `src/Strings/` folder as `.resw` files
213+
- Use `TableViewLocalizedStrings` class to access localized strings
214+
- Support for multiple languages
215+
216+
## Documentation
217+
218+
- Project uses DocFX for documentation generation
219+
- Documentation source is in `docs/` folder
220+
- Auto-generated API reference
221+
- CI workflow builds and publishes docs automatically
222+
- Documentation site: https://w-ahmad.github.io/WinUI.TableView/
223+
224+
## CI/CD Workflows
225+
226+
- **ci-build.yml**: Runs on PRs and main branch commits (non-docs)
227+
- Builds the library
228+
- Runs unit tests
229+
- Creates NuGet package artifacts
230+
231+
- **cd-build.yml**: Continuous deployment for releases
232+
- Publishes to NuGet on version tags
233+
234+
- **ci-docs.yml**: Documentation build
235+
- Triggered by changes to docs/ folder
236+
- Publishes to GitHub Pages
237+
238+
## Dependencies and Package Management
239+
240+
- Use NuGet for package management
241+
- Pin specific versions in .csproj for stability
242+
- CommunityToolkit.WinUI.Behaviors version differs between .NET 8 and 9
243+
- Microsoft.WindowsAppSDK and Uno.WinUI versions are carefully selected for compatibility
244+
245+
## Important Notes for Contributors
246+
247+
1. **Nullable Reference Types**: The project uses nullable reference types. Be mindful of null checks and use appropriate nullable annotations.
248+
249+
2. **Internal Visibility**: Tests have access to internal members via `InternalsVisibleTo` attribute.
250+
251+
3. **Performance**: This is a performance-focused control designed to handle large datasets efficiently.
252+
253+
4. **Breaking Changes**: Avoid breaking changes to public API. Discuss in issues first.
254+
255+
5. **Samples**: A separate repository (WinUI.TableView.SampleApp) contains interactive samples and demos.
256+
257+
## Getting Help
258+
259+
- **Issues**: Report bugs via GitHub Issues with bug_report.md template
260+
- **Discussions**: Ask questions in GitHub Discussions
261+
- **Feature Requests**: Use feature_request.md template in Issues
262+
263+
## License
264+
265+
This project is licensed under the MIT License. All contributions will be under the same license.

0 commit comments

Comments
 (0)