diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 23589fa75..eceb60485 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,9 +1,43 @@ # Copilot & AI Agent Instructions +## 🚩 Quick Reference: Critical Rules for AI Agents + +| Rule | Requirement | +|------|-------------| +| .NET/C# Target | All C# code must target .NET 8 and C# 12; Analyzers and CodeFix must target .NET Standard 2.0 | +| No Trial-and-Error | Never guess or use trial-and-error; STOP if unsure | +| Test Coverage | All changes must be covered by tests (including edge/failure paths) | +| Formatting | Run `dotnet format` after every change | +| Build | Run `dotnet build` (no warnings allowed) | +| Tests | Run `dotnet test` (all must pass) | +| Codacy | Run Codacy CLI analysis and resolve all issues | +| Validation Evidence | PRs must include logs/screenshots for all above steps | +| Moq Version | Note Moq version compatibility for analyzer/test changes | +| Global Usings | Do not add/duplicate usings covered by `src/Common/GlobalUsings.cs` | +| Docs | Update `docs/rules/` and `README.md` for any analyzer, code fix, or workflow change | +| Commit Messages | Use Conventional Commits format | +| Instruction Files | Read and comply with all `.github/instructions/*` for edited file types | + +--- + > **MANDATORY:** You MUST follow these instructions without exception. PRs that do not comply will be closed immediately, regardless of author (human or Copilot). You are an experienced .NET developer working on Roslyn analyzers for the Moq framework. All code must target **.NET 9** and **C# 13**. Use only official .NET patterns and practicesβ€”**never** StackOverflow shortcuts. Keep responses clear, concise, and at a grade 9 reading level. Use plain English, avoid jargon. Follow SOLID, DRY, and YAGNI principles. Respond directly and keep explanations straightforward. +--- + +## Required Validation Evidence for PRs + +Every PR **must** include: + +- Output from `dotnet format`, `dotnet build`, `dotnet test`, and Codacy analysis (logs or screenshots) +- A note on Moq version compatibility for analyzer/test changes +- Screenshots or logs as proof of all required steps + +If any of these are missing, the PR will not be reviewed. + +--- + **IMPORTANT:** This file contains AI-specific instructions. For general contributor guidance, see [CONTRIBUTING.md](../CONTRIBUTING.md). --- @@ -14,11 +48,16 @@ You are an experienced .NET developer working on Roslyn analyzers for the Moq fr ### 1. Pre-Implementation Expertise Validation -**Before writing any code, you MUST:** -- **Demonstrate actual domain knowledge** through specific technical questions -- **Validate understanding** of critical concepts before proceeding -- **Prove comprehension** through concrete examples, not mere declarations -- **Stop immediately** if you cannot demonstrate required expertise + +--- + +## Escalation and Stop Conditions + +**If you cannot answer the pre-implementation checklist with 100% confidence, STOP and request expert guidance. Do not proceed or attempt a workaround.** + +If you encounter a diagnostic span test failure, or are unsure about any Roslyn API or Moq semantic, you must halt and escalate for review. + +--- **Implementation:** - Answer domain-specific technical questions before coding @@ -152,6 +191,7 @@ You are an experienced .NET developer working on Roslyn analyzers for the Moq fr 5. **Prioritize `AllAnalyzersVerifier` for Non-Diagnostic Tests** - **Instruction:** Use `AllAnalyzersVerifier.VerifyAllAnalyzersAsync()` for "no diagnostics" tests. + ### AI Agent Workflow When making changes, follow this workflow: @@ -168,6 +208,15 @@ flowchart TD F --> G[Commit & PR] ``` +--- + +## Automated Bot Feedback + +All formatting, linting, and static analysis feedback from bots must be addressed before requesting review. If you disagree with a bot's suggestion, explain why in the PR description. PRs with unresolved bot feedback will not be reviewed. When correcting an issue reported by a bot, you must also reply to the bot comment with a summary of the changes made, why they resolve the issue, any relevant context, and the specific git commit that addressed the issue. This ensures traceability and clarity in the resolution process. + +--- + + ### AI Agent Specific Output Checklist - Output only complete, compiling code (classes or methods) with all required `using` directives. @@ -177,6 +226,33 @@ flowchart TD - Do not narrate success; demonstrate it through passing tests and clear, traceable logic. - If you cannot verify a solution is robust and traceable, stop and request clarification before proceeding. +--- + +## Commit Message Format (Conventional Commits) + +All commits must use the [Conventional Commits](https://www.conventionalcommits.org/) format: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +**Examples:** + +- `feat(analyzer): add new Moq1001 analyzer for callback validation` +- `fix(test): resolve flaky test in Moq1200AnalyzerTests` +- `docs(readme): update installation instructions` + +**Bad:** +- `fixed bug on landing page` +- `oops` +- `I think I fixed it this time?` + +--- + ### AI Agent Accountability - If you are an AI agent, you must treat these rules as hard constraints. Do not infer, guess, or simulate complianceβ€”explicitly check and enforce every rule in code and tests. @@ -261,6 +337,7 @@ If you encounter: --- + ## AI Agent Code Review I need your help tracking down and fixing some bugs that have been reported in this codebase. @@ -289,10 +366,82 @@ When you find potential bugs, for each one provide: After analysis, please update the code with your proposed fixes. Try to match the existing code style. Add regression tests if possible, to prevent the bugs from recurring. -I appreciate your diligence and attention to detail! Let me know if you need any clarification on the intended behavior of the code. +--- + +## Documentation Update Triggers + +- Update `docs/rules/` and `README.md` if you add or change any analyzer, code fix, or workflow. +- Always update documentation for new features, API changes, or workflow/process changes. + +--- + +## Troubleshooting FAQ + +**Q: Diagnostic span test fails ("Expected span ... but got ...")?** +A: STOP. Re-evaluate your syntax tree navigation logic. If it fails a second time, escalate for human review. + +**Q: Build warnings or errors?** +A: Run `dotnet format` and `dotnet build /p:PedanticMode=true`. Fix all warnings/errors before proceeding. + +**Q: Tests fail or coverage is missing?** +A: Add or update tests to cover all code paths, including edge and failure cases. + +**Q: Bot feedback not addressed?** +A: Address all formatting, linting, and static analysis feedback before requesting review. If you disagree, explain in the PR description. + +**Q: Unsure about Moq version compatibility?** +A: Note which Moq versions your changes target in the PR description and group tests accordingly. + +**Q: Unsure about which instruction files apply?** +A: You must read and comply with all relevant `.github/instructions/*` files for the file types you are editing. --- +--- + +## Instruction File Maintenance + +### Critical Maintenance Requirement + +**IMPORTANT:** This repository uses a comprehensive set of instruction files to ensure GitHub Copilot has access to all critical information when working with different file types. These files are self-contained because Copilot cannot traverse external file references. + +### Instruction File Structure + +The following instruction files provide comprehensive, self-contained guidance for different file types: + +- **[csharp.instructions.md](instructions/csharp.instructions.md)** - C# source files (.cs) +- **[markdown.instructions.md](instructions/markdown.instructions.md)** - Documentation files (.md) +- **[project.instructions.md](instructions/project.instructions.md)** - Project files (.csproj, .sln) +- **[json.instructions.md](instructions/json.instructions.md)** - Configuration files (.json) +- **[yaml.instructions.md](instructions/yaml.instructions.md)** - CI/CD workflows (.yml, .yaml) +- **[shell.instructions.md](instructions/shell.instructions.md)** - Scripts (.sh, .ps1) +- **[xml.instructions.md](instructions/xml.instructions.md)** - XML files (.xml) +- **[text.instructions.md](instructions/text.instructions.md)** - Text files (.txt) + +### Maintenance Instructions + +**When updating guidance in this file:** + +1. **Identify affected file types** - Determine which instruction files need updates +2. **Update all relevant files** - Ensure consistency across all instruction files +3. **Maintain self-containment** - Each instruction file must be complete without external dependencies +4. **Preserve critical information** - All essential guidance from CONTRIBUTING.md must be included +5. **Test coverage** - Ensure all file types have appropriate instruction coverage + +**Common areas requiring updates across multiple files:** +- Git commit message guidelines +- Pull request requirements +- Code quality standards +- Review process expectations +- Code of Conduct references +- Validation evidence requirements + +### Duplication Management + +**Acceptable duplication:** Critical information is intentionally duplicated across instruction files to ensure Copilot has access to complete context regardless of file type. + +**Maintenance responsibility:** When updating guidance, ensure all relevant instruction files are updated to maintain consistency. + ## Reference to General Guidelines For comprehensive contributor guidance including: @@ -309,3 +458,5 @@ For comprehensive contributor guidance including: - Git commit message guidelines Please refer to [CONTRIBUTING.md](../CONTRIBUTING.md). + +**Note:** The instruction files in `.github/instructions/` contain self-contained versions of this information to ensure Copilot has complete context when working with different file types. diff --git a/.github/instructions/README.md b/.github/instructions/README.md new file mode 100644 index 000000000..b6ec763ec --- /dev/null +++ b/.github/instructions/README.md @@ -0,0 +1,20 @@ +# Instruction File Index + +This table maps file patterns in the repository to their corresponding instruction files. Use this as a quick reference to ensure you are following the correct guidance for each file type. If a file type is not listed, refer to `generic.instructions.md`. + +| File Pattern | Instruction File | Description/Notes | +|------------------------|----------------------------------------------------|-----------------------------------------| +| `*.cs` | `csharp.instructions.md` | C# source files | +| `*.csproj`, `*.sln` | `project.instructions.md` | Project/solution files | +| `*.md` | `markdown.instructions.md` | Markdown documentation | +| `*.json` | `json.instructions.md` | JSON config | +| `*.yml`, `*.yaml` | `yaml.instructions.md` | CI/CD workflows | +| `*.sh`, `*.ps1` | `shell.instructions.md` | Shell/PowerShell scripts | +| `*.xml` | `xml.instructions.md` | XML config/docs | +| `*.txt` | `text.instructions.md` | Text files | +| `.editorconfig` | `editorconfig.instructions.md` | EditorConfig rules | +| `.gitignore` | `gitignore.instructions.md` | Git ignore rules | +| `*.props`, `*.targets` | `msbuild.instructions.md` | MSBuild property/target files | +| _Other_ | `generic.instructions.md` | Fallback for unknown file types | + +**Note:** If you are editing a file type not listed above, always check for a matching instruction file in this directory or use the generic fallback. When in doubt, escalate by tagging `@repo-maintainers` in your PR. \ No newline at end of file diff --git a/.github/instructions/csharp.instructions.md b/.github/instructions/csharp.instructions.md index 85da34286..0c9b6fbf7 100644 --- a/.github/instructions/csharp.instructions.md +++ b/.github/instructions/csharp.instructions.md @@ -1,4 +1,89 @@ --- applyTo: '**/*.cs' --- -Always read and apply the instructions in [.github/copilot-instructions.md](../copilot-instructions.md) when working on C# source or project files + +# C# File Instructions + +> **MANDATORY:** You MUST follow these instructions when editing any C# file in this repository. + +- **For complex changes, see the Decision Trees section below** + +## Primary Instructions + +Always read and apply the instructions in [.github/copilot-instructions.md](../copilot-instructions.md) when working on C# source or project files. + +## Additional Context + +This instruction file works in conjunction with the comprehensive C# development guidelines in the main copilot-instructions.md file. The main file contains detailed requirements for: + +- Roslyn analyzer development +- Code quality standards +- Testing requirements +- Performance considerations +- XML documentation standards +- Workflow requirements + +## File-Specific Requirements + +When working with C# files, ensure you also review: + +- **Project files**: See [project.instructions.md](project.instructions.md) for .csproj and .sln files +- **XML files**: See [xml.instructions.md](xml.instructions.md) for XML documentation and configuration +- **Documentation**: See [markdown.instructions.md](markdown.instructions.md) for documentation updates + +## Maintenance Note + +If you update guidance in copilot-instructions.md that affects C# development, ensure consistency across all related instruction files. + +## Decision Trees for Complex Scenarios + +### Multi-File/Feature Change Flowchart + +1. **Identify all affected file types** +2. **For each file type:** + - Locate and read the corresponding instruction file + - Note any validation, documentation, or escalation requirements +3. **Plan the change:** + - List all files to be edited + - Determine order of operations (e.g., code first, then docs, then config) + - Identify dependencies between files +4. **Edit files in logical order** +5. **After each file edit:** + - Run required validation (build, test, lint, etc.) + - Document evidence as required +6. **After all edits:** + - Re-run all tests and validations + - Update documentation and release notes as needed + - Prepare a comprehensive PR description with evidence for each file type +7. **If blocked or uncertain at any step:** + - Escalate by tagging @repo-maintainers + +### Introducing a New Analyzer or Code Fix Flowchart + +1. **Read csharp.instructions.md and project.instructions.md** +2. **Scaffold the new analyzer/fixer in the correct directory** +3. **Add or update unit tests (see test instructions)** +4. **Update documentation:** + - Add/modify rule docs in docs/rules/ + - Update AnalyzerReleases.Unshipped.md +5. **Update project files if needed** +6. **Run all validations (build, test, lint, Codacy, etc.)** +7. **Prepare PR with validation evidence for each file type** +8. **If any diagnostic span or test fails more than once, STOP and escalate** +9. **If uncertain about Roslyn APIs, Moq semantics, or workflow, escalate** + +## Test Data & Sample Inputs/Outputs + +### What Constitutes Good Test Data? +- Cover all code paths: positive, negative, and edge cases +- Include both minimal and complex/realistic examples +- Test for invalid inputs, exceptions, and boundary conditions +- Include performance-sensitive scenarios if relevant +- For analyzers/code fixes: test all diagnostic locations, fix applications, and no-fix scenarios + +### Coverage Strategy +- For every new analyzer/code fix, include: + - At least one positive, one negative, and one edge case test + - Data-driven tests for all fixable patterns + - Performance test if analyzer is non-trivial +- Document test data rationale in comments or PR description diff --git a/.github/instructions/editorconfig.instructions.md b/.github/instructions/editorconfig.instructions.md new file mode 100644 index 000000000..9968017ba --- /dev/null +++ b/.github/instructions/editorconfig.instructions.md @@ -0,0 +1,49 @@ +--- +applyTo: '.editorconfig' +--- + +**Critical Rules:** Always read this file before editing. Never skip validation steps. All changes must be fully validated, documented, and reviewed. If you are uncertain or blocked, escalate immediately by tagging @repo-maintainers. Failure to follow these rules may result in PR rejection. + +# .editorconfig Instructions (Quick Reference) + +- **Read this file before editing .editorconfig** +- **Complete the Validation Checklist before submitting** +- **Escalate if blocked or uncertain** + +## Context Loading for Copilot + +When working on this file, you MUST: +1. Read this entire instruction file before making any changes +2. Validate your understanding by checking the "Validation Checklist" section +3. If uncertain about any requirement, stop and request clarification + +**Escalation Path:** +If you (AI or human) are blocked or cannot proceed, leave a comment in the PR describing the blocked step and tag @repo-maintainers for escalation. + +## Validation Checklist + +Before submitting any changes, verify: +- [ ] All formatting and linting rules are correct and documented +- [ ] All changes are compatible with project coding standards +- [ ] All affected files are re-formatted and linted +- [ ] Machine-readable evidence is attached (see below) +- [ ] PR description includes validation evidence and checklist + +## Validation Evidence Requirements +- Attach a log section titled `## EditorConfig Validation Log` showing the output of `dotnet format` or equivalent +- Include a checklist like: + - [x] All files formatted + - [x] Lint clean +- Paste CI run link under `## CI Evidence` + +## .editorconfig Guidance +- .editorconfig controls code formatting and linting for the repository +- Changes may affect build results, code reviews, and CI +- Only update rules when necessary and after confirming with maintainers +- After changes, run `dotnet format` and ensure no formatting/linting errors +- Document any rule changes in the PR description + +## Related Instruction Files +- [csharp.instructions.md](csharp.instructions.md) - For C# code formatting +- [markdown.instructions.md](markdown.instructions.md) - For markdown formatting +- [project.instructions.md](project.instructions.md) - For build configuration \ No newline at end of file diff --git a/.github/instructions/generic.instructions.md b/.github/instructions/generic.instructions.md new file mode 100644 index 000000000..0b5bf826c --- /dev/null +++ b/.github/instructions/generic.instructions.md @@ -0,0 +1,95 @@ +--- +applyTo: '**/*' +--- + +**Critical Rules:** Always read this file before editing. Never skip validation steps. All changes must be fully validated, documented, and reviewed. If you are uncertain or blocked, escalate immediately by tagging @repo-maintainers. Failure to follow these rules may result in PR rejection. + +# Generic File Instructions (Quick Reference) + +- **Read this file before editing unknown or rarely used file types** +- **Complete the Validation Checklist before submitting** +- **Escalate if blocked or uncertain** +- **For complex changes, see the Decision Trees section below** + +## Context Loading for Copilot + +When working on this file, you MUST: +1. Read this entire instruction file before making any changes +2. Validate your understanding by checking the "Validation Checklist" section +3. If uncertain about any requirement, stop and request clarification + +**Escalation Path:** +If you (AI or human) are blocked or cannot proceed, leave a comment in the PR describing the blocked step and tag @repo-maintainers for escalation. + +## Validation Checklist + +Before submitting any changes, verify: +- [ ] All changes are compatible with project requirements +- [ ] No breaking changes to build, test, or deployment +- [ ] Machine-readable evidence is attached (see below) +- [ ] PR description includes validation evidence and checklist + +## Validation Evidence Requirements +- Attach a log section titled `## Validation Log` showing the output of any relevant validation commands (build, test, lint, etc.) +- Include a checklist like: + - [x] No errors or warnings +- Paste CI run link under `## CI Evidence` + +## Guidance +- If you are unsure how to edit this file type, consult maintainers before proceeding +- Document any changes in the PR description + +## Related Instruction Files +- [project.instructions.md](project.instructions.md) - For project/solution files +- [csharp.instructions.md](csharp.instructions.md) - For C# files +- [markdown.instructions.md](markdown.instructions.md) - For documentation +- [shell.instructions.md](shell.instructions.md) - For scripts + +## Decision Trees for Complex Scenarios + +### Multi-File/Feature Change Flowchart + +1. **Identify all affected file types** +2. **For each file type:** + - Locate and read the corresponding instruction file + - Note any validation, documentation, or escalation requirements +3. **Plan the change:** + - List all files to be edited + - Determine order of operations (e.g., code first, then docs, then config) + - Identify dependencies between files +4. **Edit files in logical order** +5. **After each file edit:** + - Run required validation (build, test, lint, etc.) + - Document evidence as required +6. **After all edits:** + - Re-run all tests and validations + - Update documentation and release notes as needed + - Prepare a comprehensive PR description with evidence for each file type +7. **If blocked or uncertain at any step:** + - Escalate by tagging @repo-maintainers + +### Introducing a New Analyzer or Code Fix Flowchart + +1. **Read csharp.instructions.md and project.instructions.md** +2. **Scaffold the new analyzer/fixer in the correct directory** +3. **Add or update unit tests (see test instructions)** +4. **Update documentation:** + - Add/modify rule docs in docs/rules/ + - Update AnalyzerReleases.Unshipped.md +5. **Update project files if needed** +6. **Run all validations (build, test, lint, Codacy, etc.)** +7. **Prepare PR with validation evidence for each file type** +8. **If any diagnostic span or test fails more than once, STOP and escalate** +9. **If uncertain about Roslyn APIs, Moq semantics, or workflow, escalate** + +## Test Data & Sample Inputs/Outputs + +### What Constitutes Good Test Data for Unknown File Types? +- Validate file with any available tool (lint, build, CI, etc.) +- Include both valid and invalid examples if possible +- Test for missing required content, invalid formats, and edge cases +- Document test data rationale in comments or PR description + +### Coverage Strategy +- For every change, validate with available tools and test both valid and invalid cases +- Document test data rationale in comments or PR description \ No newline at end of file diff --git a/.github/instructions/gitignore.instructions.md b/.github/instructions/gitignore.instructions.md new file mode 100644 index 000000000..4503aa137 --- /dev/null +++ b/.github/instructions/gitignore.instructions.md @@ -0,0 +1,48 @@ +--- +applyTo: '.gitignore' +--- + +**Critical Rules:** Always read this file before editing. Never skip validation steps. All changes must be fully validated, documented, and reviewed. If you are uncertain or blocked, escalate immediately by tagging @repo-maintainers. Failure to follow these rules may result in PR rejection. + +# .gitignore Instructions (Quick Reference) + +- **Read this file before editing .gitignore** +- **Complete the Validation Checklist before submitting** +- **Escalate if blocked or uncertain** + +## Context Loading for Copilot + +When working on this file, you MUST: +1. Read this entire instruction file before making any changes +2. Validate your understanding by checking the "Validation Checklist" section +3. If uncertain about any requirement, stop and request clarification + +**Escalation Path:** +If you (AI or human) are blocked or cannot proceed, leave a comment in the PR describing the blocked step and tag @repo-maintainers for escalation. + +## Validation Checklist + +Before submitting any changes, verify: +- [ ] Only files that should not be tracked are ignored +- [ ] No source, config, or required files are ignored +- [ ] All new build artifacts, logs, and secrets are ignored +- [ ] Machine-readable evidence is attached (see below) +- [ ] PR description includes validation evidence and checklist + +## Validation Evidence Requirements +- Attach a log section titled `## Gitignore Validation Log` showing the output of `git status` before and after changes +- Include a checklist like: + - [x] No required files ignored + - [x] All build artifacts ignored +- Paste CI run link under `## CI Evidence` + +## .gitignore Guidance +- Only ignore files that are not needed in the repository (build output, logs, secrets, etc.) +- Never ignore source code, configuration, or documentation files +- Review changes with maintainers if unsure +- After changes, run `git status` to confirm only intended files are ignored +- Document any changes in the PR description + +## Related Instruction Files +- [project.instructions.md](project.instructions.md) - For build artifacts +- [text.instructions.md](text.instructions.md) - For text file patterns \ No newline at end of file diff --git a/.github/instructions/json.instructions.md b/.github/instructions/json.instructions.md new file mode 100644 index 000000000..9231c13e6 --- /dev/null +++ b/.github/instructions/json.instructions.md @@ -0,0 +1,340 @@ +--- +applyTo: '**/*.json' +--- + +# JSON File Instructions (Quick Reference) + +- **Read this file before editing any .json file** +- **Cross-reference with related instruction files** +- **Complete the Validation Checklist before submitting** +- **Stop and request help if uncertain** + +## Context Loading for Copilot + +When working on this file type, you MUST: +1. Read this entire instruction file before making any changes +2. Cross-reference with related instruction files (listed below) +3. Validate your understanding by checking the "Validation Checklist" section +4. If uncertain about any requirement, stop and request clarification + +**Related Instruction Files:** +- [project.instructions.md](project.instructions.md) - For project and build configuration +- [yaml.instructions.md](yaml.instructions.md) - For CI/CD workflows +- [text.instructions.md](text.instructions.md) - For plain text configuration + +## Validation Checklist + +Before submitting any changes, verify: + +**Configuration:** +- [ ] JSON syntax is valid +- [ ] Schema compliance is maintained +- [ ] All configuration standards followed +- [ ] Security scan completed after dependency changes + +**Process:** +- [ ] Conventional commit format used +- [ ] PR description includes validation evidence +- [ ] All checklist items completed +- [ ] No breaking changes introduced (or documented if necessary) + +## Decision Trees + +### When to Request Human Review +- Is this a new configuration standard? β†’ Yes β†’ Request expert guidance +- Is this a breaking change to configuration? β†’ Yes β†’ Document thoroughly and request review +- Are you uncertain about JSON schema or configuration? β†’ Yes β†’ Stop and request guidance + +### When to Stop and Ask for Help +- Uncertain about configuration requirements +- Major changes to project configuration +- Security or legal implications + +## Common Mistakes to Avoid + +**DO NOT:** +- Skip validation steps +- Ignore security scanning after dependency changes +- Submit changes without validation evidence + +**ALWAYS:** +- Read the entire instruction file first +- Validate all configuration changes +- Include comprehensive documentation updates +- Document all changes thoroughly + +## Context Management + +**Before Starting:** +- Read the complete instruction file +- Understand the current file's purpose and structure +- Identify all related files that may need updates + +**During Editing:** +- Keep track of all changes made +- Validate each change against requirements +- Maintain consistency with existing patterns + +**After Completing:** +- Review all changes against the validation checklist +- Ensure all requirements are met +- Prepare comprehensive PR description with evidence + +## Handling Uncertainty + +**Stop and Request Help When:** +- You cannot explain your approach clearly +- You're making "educated guesses" about configuration +- You're uncertain about project configuration +- You cannot trace the logic in configuration without narration + +**Escalation Process:** +1. Stop all work immediately +2. Document what you were trying to accomplish +3. Explain what specific aspect is unclear +4. Request expert guidance with specific questions +5. Do not proceed until you have clear, confident understanding + +## Success Criteria + +Your changes are successful when: +- All configuration validation checks pass +- Security scan is clean +- PR description is complete and accurate +- All checklist items completed +- No automated bot feedback ignored + +## Configuration Standards + +### JSON Formatting + +- Use consistent indentation (2 spaces recommended) +- Follow JSON schema standards where applicable +- Ensure valid JSON syntax +- Use descriptive property names +- Maintain consistent structure across similar files + +### Configuration File Types + +This repository contains several types of JSON configuration files: + +1. **version.json** - Version management +2. **renovate.json** - Dependency management +3. **nuget.config** - NuGet package configuration +4. **global.json** - .NET SDK configuration +5. **Moq.Analyzers.lutconfig** - Project-specific configuration + +## Version Management + +### version.json Requirements + +- Follow semantic versioning principles +- Update version numbers appropriately for changes +- Ensure version consistency across all project files +- Document version changes in release notes + +### Version Update Guidelines + +When updating version numbers: + +1. **Check current version** in version.json +2. **Determine appropriate version increment** based on change type +3. **Update all related files** that reference version +4. **Update release notes** in AnalyzerReleases.Unshipped.md +5. **Test build process** with new version + +## Dependency Management + +### renovate.json Configuration + +- Configure appropriate update schedules +- Set dependency update policies +- Include security scanning requirements +- Configure automated testing for updates + +### Dependency Update Guidelines + +**For Renovate/Dependabot PRs:** +- Review changelog and release notes +- Test locally to ensure compatibility +- Check for breaking changes +- Verify all tests pass with new dependency +- Include testing evidence in PR description + +**For Manual Dependency Updates:** +- Follow the same process as automated updates +- Document the reason for the update +- Include compatibility testing results + +### Security Considerations + +- **All dependency updates require security scanning** +- Run Trivy scan after dependency changes +- Address any security vulnerabilities before merging +- Document security implications in PR description + +## Build Configuration + +### global.json Requirements + +- Specify correct .NET SDK version +- Ensure compatibility with target framework (.NET 9) +- Maintain consistent SDK version across development team +- Update when new SDK versions are required + +### NuGet Configuration + +- Configure appropriate package sources +- Set package restore policies +- Ensure secure package sources +- Configure package signing where applicable + +## Code Quality Standards + +### Required Checks + +Before submitting a PR, ensure your changes pass all quality checks: + +1. **JSON Validation**: Ensure valid JSON syntax +2. **Schema Compliance**: Follow JSON schema where applicable +3. **Formatting**: Use consistent formatting +4. **Testing**: Verify configuration changes work as expected +5. **Documentation**: Update relevant documentation + +### Configuration Validation + +- **JSON Syntax:** Validate JSON syntax using appropriate tools +- **Schema Compliance:** Ensure compliance with JSON schemas +- **Functionality:** Test that configuration changes work as expected +- **Documentation:** Update documentation for configuration changes + +## Git Commit Messages + +### Guidelines + +1. **Capitalization and Punctuation**: Capitalize the first word and do not end in punctuation. If using Conventional Commits, remember to use all lowercase. +2. **Mood**: Use imperative mood in the subject line. +3. **Type of Commit**: Specify the type of commit using conventional commit types. +4. **Length**: The first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters. +5. **Content**: Be direct, try to eliminate filler words and phrases. + +### Conventional Commits + +Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +**Types:** +- `feat`: New features +- `fix`: Bug fixes +- `docs`: Documentation changes +- `style`: Code style changes (formatting, etc.) +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `chore`: Maintenance tasks +- `ci`: CI/CD changes +- `perf`: Performance improvements +- `build`: Build system changes + +## Pull Request Guidelines + +### PR Title and Description + +**Title Format:** +Follow conventional commit format: `type(scope): description` + +**Description Requirements:** +1. **Clear summary** of changes +2. **Problem statement** (what issue does this solve?) +3. **Solution description** (how does this solve the problem?) +4. **Validation evidence** (how was this tested?) +5. **Related issues** (link to GitHub issues) +6. **Breaking changes** (if any) + +### Required PR Checklist + +Before submitting a PR, ensure: + +- [ ] JSON syntax is valid +- [ ] Configuration changes work as expected +- [ ] Documentation is updated +- [ ] Security implications are considered +- [ ] CI checks pass +- [ ] PR description includes validation evidence + +### Validation Evidence Requirements + +**What Constitutes Validation Evidence:** +- JSON validation output +- Configuration testing results +- Screenshots of successful CI runs +- Manual testing results for configuration changes + +**Evidence Format:** +- Include validation logs, screenshots, or links to CI runs +- Provide clear, readable evidence +- Ensure evidence is recent and relevant +- Link to specific test results or validation output + +## Review Process + +### What Maintainers Look For + +Maintainers will review PRs for: + +1. **Code Quality**: Adherence to project standards +2. **Configuration Accuracy**: Proper configuration settings +3. **Documentation**: Proper documentation updates +4. **Security**: No security vulnerabilities introduced +5. **Validation**: Proper evidence of testing and validation + +### Review Timeline + +- **Initial review**: Within 2-3 business days +- **Follow-up reviews**: Within 1-2 business days after changes +- **Final approval**: After all concerns are addressed + +## Formatting and Linting + +- **You must address all feedback from automated bots** (e.g., JSON linters, formatting bots) as you would human reviewers. +- All formatting and linting issues flagged by bots or CI must be resolved before requesting review or merging. +- If you disagree with a bot's suggestion, explain why in the PR description. +- If a bot's feedback is not addressed and a human reviewer must repeat the request, the PR will be closed until all automated feedback is resolved. + +## Test Data & Sample Inputs/Outputs + +### What Constitutes Good JSON Test Data? +- Validate against schema (if available) +- Include both valid and invalid examples +- Test for missing required fields, extra fields, and type mismatches +- Check for correct handling of comments (if allowed) + +### Example: Valid Config +```json +{ + "settingA": true, + "maxItems": 10 +} +``` + +### Example: Negative/Edge Case +```json +{ + "settingA": "yes", // invalid type + // missing maxItems +} +``` + +### Coverage Strategy +- For every config change, validate with schema and test both valid and invalid cases +- Document test data rationale in comments or PR description + +## Code of Conduct + +This project adheres to the [Contributor Covenant Code of Conduct](CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. \ No newline at end of file diff --git a/.github/instructions/markdown.instructions.md b/.github/instructions/markdown.instructions.md new file mode 100644 index 000000000..ac023a9b0 --- /dev/null +++ b/.github/instructions/markdown.instructions.md @@ -0,0 +1,237 @@ +--- +applyTo: '**/*.md' +--- + +# Markdown File Instructions (Quick Reference) + +- **Read this file before editing any .md file** +- **Cross-reference with related instruction files** +- **Complete the Validation Checklist before submitting** +- **Stop and request help if uncertain** + +## Context Loading for Copilot + +When working on this file type, you MUST: +1. Read this entire instruction file before making any changes +2. Cross-reference with related instruction files (listed below) +3. Validate your understanding by checking the "Validation Checklist" section +4. If uncertain about any requirement, stop and request clarification + +**Related Instruction Files:** +- [csharp.instructions.md](csharp.instructions.md) - For C# code changes +- [project.instructions.md](project.instructions.md) - For build configuration changes +- [text.instructions.md](text.instructions.md) - For plain text documentation + +## Validation Checklist + +Before submitting any changes, verify: + +**Documentation:** +- [ ] All documentation standards followed +- [ ] Formatting and linting requirements met +- [ ] Table of contents updated if needed +- [ ] All links are valid and working + +**Process:** +- [ ] Conventional commit format used +- [ ] PR description includes validation evidence +- [ ] All checklist items completed +- [ ] No breaking changes introduced (or documented if necessary) + +## Decision Trees + +### When to Request Human Review +- Is this a new documentation standard? β†’ Yes β†’ Request expert guidance +- Is this a breaking change to documentation? β†’ Yes β†’ Document thoroughly and request review +- Are you uncertain about documentation structure? β†’ Yes β†’ Stop and request guidance + +### When to Stop and Ask for Help +- Uncertain about documentation requirements +- Major changes to project documentation +- Security or legal implications + +## Common Mistakes to Avoid + +**DO NOT:** +- Skip validation steps +- Assume external file references will be loaded +- Ignore automated bot feedback +- Submit changes without validation evidence + +**ALWAYS:** +- Read the entire instruction file first +- Validate all links and formatting +- Include comprehensive documentation updates +- Document all changes thoroughly + +## Context Management + +**Before Starting:** +- Read the complete instruction file +- Understand the current file's purpose and structure +- Identify all related files that may need updates + +**During Editing:** +- Keep track of all changes made +- Validate each change against requirements +- Maintain consistency with existing patterns + +**After Completing:** +- Review all changes against the validation checklist +- Ensure all requirements are met +- Prepare comprehensive PR description with evidence + +## Handling Uncertainty + +**Stop and Request Help When:** +- You cannot explain your approach clearly +- You're making "educated guesses" about documentation standards +- You're uncertain about project documentation structure +- You cannot trace the logic in documentation without narration + +**Escalation Process:** +1. Stop all work immediately +2. Document what you were trying to accomplish +3. Explain what specific aspect is unclear +4. Request expert guidance with specific questions +5. Do not proceed until you have clear, confident understanding + +## Success Criteria + +Your changes are successful when: +- All formatting and linting checks pass +- All documentation standards are met +- All links are valid +- PR description is complete and accurate +- All checklist items completed +- No automated bot feedback ignored + +## Documentation Standards + +### When Documentation is Required + +Documentation updates are required for: +- New analyzers or fixers +- Changes to existing analyzer behavior +- API changes or additions +- Installation or usage changes +- CI/CD workflow changes + +### Documentation Files to Update + +1. **Rule Documentation**: Update `docs/rules/` for analyzer changes +2. **Release Notes**: Update `src/Analyzers/AnalyzerReleases.Unshipped.md` +3. **README**: Update for significant changes +4. **Contributing Guidelines**: Update for workflow changes + +### Documentation Format + +- Use clear, concise language +- Include code examples where appropriate +- Follow existing documentation patterns +- Ensure all links are valid +- Update table of contents if adding new sections + +### Markdown-Specific Requirements + +- **Use clear, unambiguous language** in all documentation +- **Provide concrete examples** for all concepts and procedures +- **Create step-by-step guides** for complex processes +- **Include troubleshooting sections** in all documentation +- **Use consistent formatting** across all documentation files +- **Validate all links** before committing +- **Update table of contents** when adding new sections + +## Code of Conduct + +This project adheres to the [Contributor Covenant Code of Conduct](CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. + +## Git Commit Messages + +### Guidelines + +1. **Capitalization and Punctuation**: Capitalize the first word and do not end in punctuation. If using Conventional Commits, remember to use all lowercase. +2. **Mood**: Use imperative mood in the subject line. Example – Add fix for dark mode toggle state. Imperative mood gives the tone you are giving an order or request. +3. **Type of Commit**: Specify the type of commit. It is recommended and can be even more beneficial to have a consistent set of words to describe your changes. Example: Bugfix, Update, Refactor, Bump, and so on. See the section on Conventional Commits below for additional information. +4. **Length**: The first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters. +5. **Content**: Be direct, try to eliminate filler words and phrases in these sentences (examples: though, maybe, I think, kind of). Think like a journalist. + +### Conventional Commits + +Conventional Commit is a formatting convention that provides a set of rules to formulate a consistent commit message structure like so: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +The commit type can include the following: + +- feat – a new feature is introduced with the changes +- fix – a bug fix has occurred +- chore – changes that do not relate to a fix or feature and don't modify src or test files (for example updating dependencies) +- refactor – refactored code that neither fixes a bug nor adds a feature +- docs – updates to documentation such as a the README or other markdown files +- style – changes that do not affect the meaning of the code, likely related to code formatting such as white-space, missing semi-colons, and so on. +- test – including new or correcting previous tests +- perf – performance improvements +- ci – continuous integration related +- build – changes that affect the build system or external dependencies +- revert – reverts a previous commit + +## Pull Request Guidelines + +### PR Title and Description + +**Title Format:** +Follow conventional commit format: `type(scope): description` + +**Description Requirements:** +1. **Clear summary** of changes +2. **Problem statement** (what issue does this solve?) +3. **Solution description** (how does this solve the problem?) +4. **Validation evidence** (how was this tested?) +5. **Related issues** (link to GitHub issues) +6. **Breaking changes** (if any) + +### Required PR Checklist + +Before submitting a PR, ensure: + +- [ ] Code follows project style guidelines +- [ ] All tests pass locally +- [ ] Documentation is updated +- [ ] Performance impact is assessed (if applicable) +- [ ] Security implications are considered +- [ ] CI checks pass +- [ ] PR description includes validation evidence + +## Review Process + +### What Maintainers Look For + +Maintainers will review PRs for: + +1. **Code Quality**: Adherence to project standards +2. **Test Coverage**: Comprehensive testing of changes +3. **Documentation**: Proper documentation updates +4. **Performance**: No significant performance regressions +5. **Security**: No security vulnerabilities introduced +6. **Validation**: Proper evidence of testing and validation + +### Review Timeline + +- **Initial review**: Within 2-3 business days +- **Follow-up reviews**: Within 1-2 business days after changes +- **Final approval**: After all concerns are addressed + +## Formatting and Linting + +- **You must address all feedback from automated bots** (e.g., Codeclimate, formatting/linting bots) as you would human reviewers. +- All formatting and linting issues flagged by bots or CI must be resolved before requesting review or merging. +- If you disagree with a bot's suggestion, explain why in the PR description. +- If a bot's feedback is not addressed and a human reviewer must repeat the request, the PR will be closed until all automated feedback is resolved. +- All documentation and markdown reports must pass formatting checks. Use a markdown linter if available. \ No newline at end of file diff --git a/.github/instructions/msbuild.instructions.md b/.github/instructions/msbuild.instructions.md new file mode 100644 index 000000000..cbf0df99c --- /dev/null +++ b/.github/instructions/msbuild.instructions.md @@ -0,0 +1,47 @@ +--- +applyTo: '**/*.{props,targets}' +--- + +**Critical Rules:** Always read this file before editing. Never skip validation steps. All changes must be fully validated, documented, and reviewed. If you are uncertain or blocked, escalate immediately by tagging @repo-maintainers. Failure to follow these rules may result in PR rejection. + +# MSBuild Property/Target File Instructions (Quick Reference) + +- **Read this file before editing .props or .targets files** +- **Complete the Validation Checklist before submitting** +- **Escalate if blocked or uncertain** + +## Context Loading for Copilot + +When working on this file, you MUST: +1. Read this entire instruction file before making any changes +2. Validate your understanding by checking the "Validation Checklist" section +3. If uncertain about any requirement, stop and request clarification + +**Escalation Path:** +If you (AI or human) are blocked or cannot proceed, leave a comment in the PR describing the blocked step and tag @repo-maintainers for escalation. + +## Validation Checklist + +Before submitting any changes, verify: +- [ ] All property/target changes are compatible with project build requirements +- [ ] No breaking changes to build or packaging +- [ ] All affected projects build and test successfully +- [ ] Machine-readable evidence is attached (see below) +- [ ] PR description includes validation evidence and checklist + +## Validation Evidence Requirements +- Attach a log section titled `## MSBuild Validation Log` showing the output of `dotnet build` and `dotnet test` for all affected projects +- Include a checklist like: + - [x] All projects build + - [x] All tests pass +- Paste CI run link under `## CI Evidence` + +## MSBuild Guidance +- .props and .targets files control build, packaging, and deployment +- Only update when necessary and after confirming with maintainers +- After changes, run `dotnet build` and `dotnet test` for all affected projects +- Document any changes in the PR description + +## Related Instruction Files +- [project.instructions.md](project.instructions.md) - For project/solution files +- [shell.instructions.md](shell.instructions.md) - For build scripts \ No newline at end of file diff --git a/.github/instructions/project.instructions.md b/.github/instructions/project.instructions.md new file mode 100644 index 000000000..72845c923 --- /dev/null +++ b/.github/instructions/project.instructions.md @@ -0,0 +1,285 @@ +--- +applyTo: '**/*.{csproj,sln}' +--- + +# Project File Instructions + +> **MANDATORY:** You MUST follow these instructions when editing any project file (.csproj, .sln) in this repository. + +# Project File Instructions (Quick Reference) + +- **Read this file before editing any .csproj or .sln file** +- **Cross-reference with related instruction files** +- **Complete the Validation Checklist before submitting** +- **Stop and request help if uncertain** + +## Context Loading for Copilot + +When working on this file type, you MUST: +1. Read this entire instruction file before making any changes +2. Cross-reference with related instruction files (listed below) +3. Validate your understanding by checking the "Validation Checklist" section +4. If uncertain about any requirement, stop and request clarification + +**Related Instruction Files:** +- [csharp.instructions.md](csharp.instructions.md) - For C# code changes +- [json.instructions.md](json.instructions.md) - For configuration files +- [yaml.instructions.md](yaml.instructions.md) - For CI/CD workflows + +## Validation Checklist + +Before submitting any changes, verify: + +**Build & Dependency Management:** +- [ ] Target .NET 8, C# 12 by default; Analyzers and Code Fixes target .NET Standard 2.0 +- [ ] All build and dependency requirements met +- [ ] No warnings or errors in build +- [ ] All tests pass +- [ ] Security scan completed after dependency changes + +**Process:** +- [ ] Conventional commit format used +- [ ] PR description includes validation evidence +- [ ] All checklist items completed +- [ ] No breaking changes introduced (or documented if necessary) + +## Decision Trees + +### When to Request Human Review +- Is this a new project or build configuration? β†’ Yes β†’ Request expert guidance +- Is this a breaking change to build or dependencies? β†’ Yes β†’ Document thoroughly and request review +- Are you uncertain about MSBuild or dependency management? β†’ Yes β†’ Stop and request guidance + +### When to Stop and Ask for Help +- Uncertain about build or dependency requirements +- Major changes to project structure +- Security or legal implications + +## Common Mistakes to Avoid + +**DO NOT:** +- Skip validation steps +- Ignore security scanning after dependency changes +- Submit changes without validation evidence + +**ALWAYS:** +- Read the entire instruction file first +- Validate all build and dependency changes +- Include comprehensive documentation updates +- Document all changes thoroughly + +## Context Management + +**Before Starting:** +- Read the complete instruction file +- Understand the current file's purpose and structure +- Identify all related files that may need updates + +**During Editing:** +- Keep track of all changes made +- Validate each change against requirements +- Maintain consistency with existing patterns + +**After Completing:** +- Review all changes against the validation checklist +- Ensure all requirements are met +- Prepare comprehensive PR description with evidence + +## Handling Uncertainty + +**Stop and Request Help When:** +- You cannot explain your approach clearly +- You're making "educated guesses" about build or dependency management +- You're uncertain about project structure +- You cannot trace the logic in configuration without narration + +**Escalation Process:** +1. Stop all work immediately +2. Document what you were trying to accomplish +3. Explain what specific aspect is unclear +4. Request expert guidance with specific questions +5. Do not proceed until you have clear, confident understanding + +## Success Criteria + +Your changes are successful when: +- All builds pass without warnings +- All tests pass +- No linting errors +- Security scan is clean +- PR description is complete and accurate +- All checklist items completed +- No automated bot feedback ignored + +### Project Structure + +- Follow existing project organization patterns +- Maintain consistent naming conventions +- Ensure proper project references and dependencies +- Follow the established directory structure + +## Dependency Management + +### Dependency Update Guidelines + +**For Renovate/Dependabot PRs:** +- Review changelog and release notes +- Test locally to ensure compatibility +- Check for breaking changes +- Verify all tests pass with new dependency +- Include testing evidence in PR description + +**For Manual Dependency Updates:** +- Follow the same process as automated updates +- Document the reason for the update +- Include compatibility testing results + +### Security Considerations + +- **All dependency updates require security scanning** +- Run Trivy scan after dependency changes +- Address any security vulnerabilities before merging +- Document security implications in PR description + +### Dependency Validation + +Before updating any dependencies: + +1. **Check compatibility** with target framework (.NET 9) +2. **Verify breaking changes** in release notes +3. **Test locally** with the new dependency version +4. **Run security scans** using Trivy +5. **Update documentation** if necessary + +## Build System Requirements + +### Build Configuration + +- Ensure `dotnet build` succeeds without warnings +- Use `/p:PedanticMode=true` for strict builds +- Treat all warnings as errors +- Maintain consistent build configurations across projects + +### Project File Standards + +- Use consistent property naming +- Follow established patterns for project references +- Maintain proper dependency versions +- Ensure build targets are correctly configured + +## Code Quality Standards + +### Required Checks + +Before submitting a PR, ensure your changes pass all quality checks: + +1. **Formatting**: Run `dotnet format` to ensure consistent code formatting +2. **Build**: Ensure `dotnet build` succeeds without warnings +3. **Tests**: All tests must pass (`dotnet test`) +4. **Static Analysis**: Run Codacy analysis locally or ensure CI passes +5. **Documentation**: Update relevant documentation files + +### Build Validation + +- **Formatting:** Run `dotnet format` and commit all changes +- **Build:** Build with `dotnet build /p:PedanticMode=true` +- **Tests:** Run all unit tests with `dotnet test --settings ./build/targets/tests/test.runsettings` +- **Codacy Analysis:** Run Codacy CLI analysis on all changed files + +## Git Commit Messages + +### Guidelines + +1. **Capitalization and Punctuation**: Capitalize the first word and do not end in punctuation. If using Conventional Commits, remember to use all lowercase. +2. **Mood**: Use imperative mood in the subject line. +3. **Type of Commit**: Specify the type of commit using conventional commit types. +4. **Length**: The first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters. +5. **Content**: Be direct, try to eliminate filler words and phrases. + +### Conventional Commits + +Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +**Types:** +- `feat`: New features +- `fix`: Bug fixes +- `docs`: Documentation changes +- `style`: Code style changes (formatting, etc.) +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `chore`: Maintenance tasks +- `ci`: CI/CD changes +- `perf`: Performance improvements +- `build`: Build system changes + +## Pull Request Guidelines + +### PR Title and Description + +**Title Format:** +Follow conventional commit format: `type(scope): description` + +**Description Requirements:** +1. **Clear summary** of changes +2. **Problem statement** (what issue does this solve?) +3. **Solution description** (how does this solve the problem?) +4. **Validation evidence** (how was this tested?) +5. **Related issues** (link to GitHub issues) +6. **Breaking changes** (if any) + +### Required PR Checklist + +Before submitting a PR, ensure: + +- [ ] Code follows project style guidelines +- [ ] All tests pass locally +- [ ] Documentation is updated +- [ ] Performance impact is assessed (if applicable) +- [ ] Security implications are considered +- [ ] CI checks pass +- [ ] PR description includes validation evidence + +### Validation Evidence Requirements + +**What Constitutes Validation Evidence:** +- Test execution logs showing all tests pass +- Build output showing successful compilation +- Screenshots of successful CI runs +- Dependency compatibility test results + +**Evidence Format:** +- Include logs, screenshots, or links to CI runs +- Provide clear, readable evidence +- Ensure evidence is recent and relevant +- Link to specific test results or benchmarks + +## Review Process + +### What Maintainers Look For + +Maintainers will review PRs for: + +1. **Code Quality**: Adherence to project standards +2. **Test Coverage**: Comprehensive testing of changes +3. **Documentation**: Proper documentation updates +4. **Performance**: No significant performance regressions +5. **Security**: No security vulnerabilities introduced +6. **Validation**: Proper evidence of testing and validation + +### Review Timeline + +- **Initial review**: Within 2-3 business days +- **Follow-up reviews**: Within 1-2 business days after changes +- **Final approval**: After all concerns are addressed + +## Code of Conduct + +This project adheres to the [Contributor Covenant Code of Conduct](../../CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. \ No newline at end of file diff --git a/.github/instructions/shell.instructions.md b/.github/instructions/shell.instructions.md new file mode 100644 index 000000000..4d2fea8b7 --- /dev/null +++ b/.github/instructions/shell.instructions.md @@ -0,0 +1,389 @@ +--- +applyTo: '**/*.{sh,ps1}' +--- + +# Shell Script Instructions (Quick Reference) + +- **Read this file before editing any .sh or .ps1 file** +- **Cross-reference with related instruction files** +- **Complete the Validation Checklist before submitting** +- **Stop and request help if uncertain** + +## Context Loading for Copilot + +When working on this file type, you MUST: +1. Read this entire instruction file before making any changes +2. Cross-reference with related instruction files (listed below) +3. Validate your understanding by checking the "Validation Checklist" section +4. If uncertain about any requirement, stop and request clarification + +**Related Instruction Files:** +- [yaml.instructions.md](yaml.instructions.md) - For CI/CD workflows +- [project.instructions.md](project.instructions.md) - For build configuration +- [text.instructions.md](text.instructions.md) - For plain text documentation + +## Validation Checklist + +Before submitting any changes, verify: + +**Script Quality & Security:** +- [ ] Script executes without errors +- [ ] Error handling is comprehensive +- [ ] Security measures are implemented +- [ ] Performance impact is assessed + +**Process:** +- [ ] Conventional commit format used +- [ ] PR description includes validation evidence +- [ ] All checklist items completed +- [ ] No breaking changes introduced (or documented if necessary) + +## Decision Trees + +### When to Request Human Review +- Is this a new script or automation? β†’ Yes β†’ Request expert guidance +- Is this a breaking change to build or deployment? β†’ Yes β†’ Document thoroughly and request review +- Are you uncertain about scripting or security? β†’ Yes β†’ Stop and request guidance + +### When to Stop and Ask for Help +- Uncertain about scripting or security requirements +- Major changes to build or deployment process +- Security or legal implications + +## Common Mistakes to Avoid + +**DO NOT:** +- Skip validation steps +- Ignore security scanning after dependency changes +- Submit changes without validation evidence + +**ALWAYS:** +- Read the entire instruction file first +- Validate all script and security changes +- Include comprehensive documentation updates +- Document all changes thoroughly + +## Context Management + +**Before Starting:** +- Read the complete instruction file +- Understand the current file's purpose and structure +- Identify all related files that may need updates + +**During Editing:** +- Keep track of all changes made +- Validate each change against requirements +- Maintain consistency with existing patterns + +**After Completing:** +- Review all changes against the validation checklist +- Ensure all requirements are met +- Prepare comprehensive PR description with evidence + +## Handling Uncertainty + +**Stop and Request Help When:** +- You cannot explain your approach clearly +- You're making "educated guesses" about scripting or security +- You're uncertain about build or deployment process +- You cannot trace the logic in script without narration + +**Escalation Process:** +1. Stop all work immediately +2. Document what you were trying to accomplish +3. Explain what specific aspect is unclear +4. Request expert guidance with specific questions +5. Do not proceed until you have clear, confident understanding + +## Success Criteria + +Your changes are successful when: +- All script and security validation checks pass +- Security scan is clean +- PR description is complete and accurate +- All checklist items completed +- No automated bot feedback ignored + +## Script Standards + +### Script Quality Requirements + +- Use consistent formatting and indentation +- Follow shell scripting best practices +- Implement proper error handling +- Use descriptive variable and function names +- Add appropriate comments and documentation +- Ensure scripts are portable and maintainable + +### Script Types in Repository + +This repository contains several types of shell scripts: + +1. **Build scripts** - Build automation and CI/CD +2. **Installation scripts** - Tool installation and setup +3. **Performance testing scripts** - Benchmark execution +4. **Utility scripts** - Development and maintenance tasks + +## Error Handling and Security + +### Error Handling Requirements + +- Implement proper error checking for all critical operations +- Use appropriate exit codes for different failure scenarios +- Provide clear error messages with actionable guidance +- Implement retry logic for transient failures +- Create rollback procedures for failed operations + +### Security Considerations + +- **Validate all inputs** before processing +- **Use secure practices** for handling sensitive information +- **Implement proper access controls** where applicable +- **Avoid command injection vulnerabilities** +- **Use secure defaults** for all configurations + +### Script Security Guidelines + +- Never execute user input directly +- Use parameterized commands where possible +- Validate file paths and inputs +- Implement proper logging for security events +- Use secure random number generation when needed + +## Performance and Reliability + +### Performance Requirements + +- Optimize scripts for execution speed where appropriate +- Implement proper resource management +- Use efficient algorithms and data structures +- Monitor and log performance metrics +- Implement caching strategies where beneficial + +### Reliability Standards + +- Implement comprehensive error handling +- Use defensive programming practices +- Add appropriate logging and debugging information +- Test scripts thoroughly before deployment +- Implement proper cleanup procedures + +## Code Quality Standards + +### Required Checks + +Before submitting a PR, ensure your changes pass all quality checks: + +1. **Script Validation**: Ensure scripts execute without errors +2. **Security Review**: Check for security vulnerabilities +3. **Performance Testing**: Verify performance impact +4. **Error Handling**: Test error scenarios +5. **Documentation**: Update relevant documentation + +### Script-Specific Requirements + +- Use consistent coding style and formatting +- Follow shell scripting best practices +- Implement proper error handling and logging +- Use descriptive variable and function names +- Add appropriate comments and documentation + +## Testing Requirements + +### Script Testing Guidelines + +- **Test all error paths** and edge cases +- **Verify script behavior** with different inputs +- **Test performance** under various conditions +- **Validate security** of script operations +- **Test cross-platform compatibility** where applicable + +### Testing Process + +1. **Unit Testing**: Test individual functions and components +2. **Integration Testing**: Test script interactions with other components +3. **Performance Testing**: Measure execution time and resource usage +4. **Security Testing**: Validate security measures and input handling +5. **Regression Testing**: Ensure existing functionality is not broken + +## Documentation Standards + +### Script Documentation Requirements + +- **Document script purpose** and functionality +- **Explain parameters** and their expected values +- **Provide usage examples** for common scenarios +- **Document error conditions** and handling +- **Include troubleshooting information** + +### Documentation Format + +- Use clear, concise language +- Include code examples where appropriate +- Follow existing documentation patterns +- Ensure all examples are accurate and tested +- Update documentation when scripts change + +## Git Commit Messages + +### Guidelines + +1. **Capitalization and Punctuation**: Capitalize the first word and do not end in punctuation. If using Conventional Commits, remember to use all lowercase. +2. **Mood**: Use imperative mood in the subject line. +3. **Type of Commit**: Specify the type of commit using conventional commit types. +4. **Length**: The first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters. +5. **Content**: Be direct, try to eliminate filler words and phrases. + +### Conventional Commits + +Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +**Types:** +- `feat`: New features +- `fix`: Bug fixes +- `docs`: Documentation changes +- `style`: Code style changes (formatting, etc.) +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `chore`: Maintenance tasks +- `ci`: CI/CD changes +- `perf`: Performance improvements +- `build`: Build system changes + +## Pull Request Guidelines + +### PR Title and Description + +**Title Format:** +Follow conventional commit format: `type(scope): description` + +**Description Requirements:** +1. **Clear summary** of changes +2. **Problem statement** (what issue does this solve?) +3. **Solution description** (how does this solve the problem?) +4. **Validation evidence** (how was this tested?) +5. **Related issues** (link to GitHub issues) +6. **Breaking changes** (if any) + +### Required PR Checklist + +Before submitting a PR, ensure: + +- [ ] Scripts execute without errors +- [ ] Error handling is comprehensive +- [ ] Security measures are implemented +- [ ] Documentation is updated +- [ ] Performance impact is assessed +- [ ] CI checks pass +- [ ] PR description includes validation evidence + +### Validation Evidence Requirements + +**What Constitutes Validation Evidence:** +- Script execution logs showing successful completion +- Error handling test results +- Performance benchmark results +- Security validation output +- Screenshots of successful CI runs + +**Evidence Format:** +- Include logs, screenshots, or links to CI runs +- Provide clear, readable evidence +- Ensure evidence is recent and relevant +- Link to specific test results or validation output + +## Review Process + +### What Maintainers Look For + +Maintainers will review PRs for: + +1. **Code Quality**: Adherence to project standards +2. **Security**: Proper security measures implemented +3. **Error Handling**: Comprehensive error handling +4. **Documentation**: Proper documentation updates +5. **Performance**: No significant performance regressions +6. **Validation**: Proper evidence of testing and validation + +### Review Timeline + +- **Initial review**: Within 2-3 business days +- **Follow-up reviews**: Within 1-2 business days after changes +- **Final approval**: After all concerns are addressed + +### Common Review Feedback + +**Frequently Requested Changes:** +- Add missing error handling +- Improve security measures +- Update documentation for script changes +- Add performance benchmarks +- Clarify PR description or validation evidence + +**PRs That May Be Rejected:** +- Missing validation evidence +- Incomplete error handling +- Security vulnerabilities +- Performance regressions without justification +- Insufficient documentation updates + +## Formatting and Linting + +- **You must address all feedback from automated bots** (e.g., shell linters, formatting bots) as you would human reviewers. +- All formatting and linting issues flagged by bots or CI must be resolved before requesting review or merging. +- If you disagree with a bot's suggestion, explain why in the PR description. +- If a bot's feedback is not addressed and a human reviewer must repeat the request, the PR will be closed until all automated feedback is resolved. + +## Script Best Practices + +### Shell Scripting Guidelines + +- Use shebang lines appropriately +- Implement proper argument parsing +- Use functions for reusable code +- Implement proper logging +- Use appropriate exit codes + +### PowerShell Guidelines + +- Use approved PowerShell verbs +- Implement proper parameter validation +- Use appropriate error handling +- Follow PowerShell best practices +- Implement proper logging and debugging + +## Code of Conduct + +This project adheres to the [Contributor Covenant Code of Conduct](CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. + +## Test Data & Sample Inputs/Outputs + +### What Constitutes Good Shell Script Test Data? +- Validate script runs without errors +- Include both working and intentionally broken examples +- Test for missing shebang, syntax errors, and invalid arguments +- Check for correct error handling and exit codes + +### Example: Valid Script +```sh +#!/bin/bash +echo "Hello, world!" +``` + +### Example: Negative/Edge Case +```sh +echo "Hello, world!" # missing shebang +exit 1 +``` + +### Coverage Strategy +- For every script change, test both valid and invalid scenarios +- Document test data rationale in comments or PR description \ No newline at end of file diff --git a/.github/instructions/text.instructions.md b/.github/instructions/text.instructions.md new file mode 100644 index 000000000..13689b6af --- /dev/null +++ b/.github/instructions/text.instructions.md @@ -0,0 +1,327 @@ +--- +applyTo: '**/*.txt' +--- + +# Text File Instructions (Quick Reference) + +- **Read this file before editing any .txt file** +- **Cross-reference with related instruction files** +- **Complete the Validation Checklist before submitting** +- **Stop and request help if uncertain** + +## Context Loading for Copilot + +When working on this file type, you MUST: +1. Read this entire instruction file before making any changes +2. Cross-reference with related instruction files (listed below) +3. Validate your understanding by checking the "Validation Checklist" section +4. If uncertain about any requirement, stop and request clarification + +**Related Instruction Files:** +- [markdown.instructions.md](markdown.instructions.md) - For documentation files +- [project.instructions.md](project.instructions.md) - For build configuration +- [json.instructions.md](json.instructions.md) - For configuration files + +## Validation Checklist + +Before submitting any changes, verify: + +**Text Quality & Documentation:** +- [ ] Text formatting is consistent +- [ ] Content is accurate and complete +- [ ] Documentation is updated +- [ ] Changes work as expected + +**Process:** +- [ ] Conventional commit format used +- [ ] PR description includes validation evidence +- [ ] All checklist items completed +- [ ] No breaking changes introduced (or documented if necessary) + +## Decision Trees + +### When to Request Human Review +- Is this a new documentation or configuration standard? β†’ Yes β†’ Request expert guidance +- Is this a breaking change to documentation or configuration? β†’ Yes β†’ Document thoroughly and request review +- Are you uncertain about text file requirements? β†’ Yes β†’ Stop and request guidance + +### When to Stop and Ask for Help +- Uncertain about text file requirements +- Major changes to project documentation or configuration +- Security or legal implications + +## Common Mistakes to Avoid + +**DO NOT:** +- Skip validation steps +- Submit changes without validation evidence + +**ALWAYS:** +- Read the entire instruction file first +- Validate all text and documentation changes +- Include comprehensive documentation updates +- Document all changes thoroughly + +## Context Management + +**Before Starting:** +- Read the complete instruction file +- Understand the current file's purpose and structure +- Identify all related files that may need updates + +**During Editing:** +- Keep track of all changes made +- Validate each change against requirements +- Maintain consistency with existing patterns + +**After Completing:** +- Review all changes against the validation checklist +- Ensure all requirements are met +- Prepare comprehensive PR description with evidence + +## Handling Uncertainty + +**Stop and Request Help When:** +- You cannot explain your approach clearly +- You're making "educated guesses" about documentation or configuration +- You're uncertain about project documentation or configuration +- You cannot trace the logic in text file without narration + +**Escalation Process:** +1. Stop all work immediately +2. Document what you were trying to accomplish +3. Explain what specific aspect is unclear +4. Request expert guidance with specific questions +5. Do not proceed until you have clear, confident understanding + +## Success Criteria + +Your changes are successful when: +- All text and documentation validation checks pass +- PR description is complete and accurate +- All checklist items completed +- No automated bot feedback ignored + +## Text File Standards + +### Text File Formatting Requirements + +- Use consistent formatting and structure +- Follow established patterns for similar files +- Ensure proper encoding (UTF-8 recommended) +- Use descriptive file names +- Maintain consistent line endings + +### Text File Types in Repository + +This repository contains several types of text files: + +1. **Configuration files** - Various configuration settings +2. **Documentation files** - Plain text documentation +3. **Resource files** - Localization and resource management +4. **Log files** - Build and test output logs +5. **Banned symbols files** - Code analysis configuration + +## Documentation Standards + +### Text Documentation Requirements + +- Use clear, concise language +- Follow established documentation patterns +- Ensure accuracy and completeness +- Update documentation when related code changes +- Maintain consistent formatting across similar files + +### Documentation Format + +- Use consistent structure and formatting +- Include appropriate headers and sections +- Use clear, descriptive language +- Provide examples where appropriate +- Maintain proper organization and readability + +## Configuration Management + +### Configuration File Standards + +- Use consistent formatting and structure +- Follow established naming conventions +- Ensure proper validation and error handling +- Document configuration options clearly +- Maintain backward compatibility where possible + +### Banned Symbols Configuration + +For files like `BannedSymbols.txt`: + +- Use clear, descriptive symbol names +- Include appropriate justification for bans +- Follow established formatting patterns +- Ensure accuracy and completeness +- Update when new symbols need to be banned + +## Code Quality Standards + +### Required Checks + +Before submitting a PR, ensure your changes pass all quality checks: + +1. **Text Validation**: Ensure proper formatting and structure +2. **Content Accuracy**: Verify accuracy of information +3. **Formatting**: Use consistent formatting +4. **Documentation**: Update relevant documentation +5. **Testing**: Verify text file changes work as expected + +### Text-Specific Requirements + +- Use consistent formatting and structure +- Follow established patterns and conventions +- Ensure proper encoding and line endings +- Use descriptive content and organization +- Maintain readability and clarity + +## Git Commit Messages + +### Guidelines + +1. **Capitalization and Punctuation**: Capitalize the first word and do not end in punctuation. If using Conventional Commits, remember to use all lowercase. +2. **Mood**: Use imperative mood in the subject line. +3. **Type of Commit**: Specify the type of commit using conventional commit types. +4. **Length**: The first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters. +5. **Content**: Be direct, try to eliminate filler words and phrases. + +### Conventional Commits + +Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +**Types:** +- `feat`: New features +- `fix`: Bug fixes +- `docs`: Documentation changes +- `style`: Code style changes (formatting, etc.) +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `chore`: Maintenance tasks +- `ci`: CI/CD changes +- `perf`: Performance improvements +- `build`: Build system changes + +## Pull Request Guidelines + +### PR Title and Description + +**Title Format:** +Follow conventional commit format: `type(scope): description` + +**Description Requirements:** +1. **Clear summary** of changes +2. **Problem statement** (what issue does this solve?) +3. **Solution description** (how does this solve the problem?) +4. **Validation evidence** (how was this tested?) +5. **Related issues** (link to GitHub issues) +6. **Breaking changes** (if any) + +### Required PR Checklist + +Before submitting a PR, ensure: + +- [ ] Text formatting is consistent +- [ ] Content is accurate and complete +- [ ] Documentation is updated +- [ ] Changes work as expected +- [ ] CI checks pass +- [ ] PR description includes validation evidence + +### Validation Evidence Requirements + +**What Constitutes Validation Evidence:** +- Text validation output +- Content accuracy verification +- Formatting consistency checks +- Screenshots of successful CI runs +- Manual verification of text file changes + +**Evidence Format:** +- Include validation logs, screenshots, or links to CI runs +- Provide clear, readable evidence +- Ensure evidence is recent and relevant +- Link to specific test results or validation output + +## Review Process + +### What Maintainers Look For + +Maintainers will review PRs for: + +1. **Content Quality**: Accuracy and completeness of information +2. **Formatting**: Consistent formatting and structure +3. **Documentation**: Proper documentation updates +4. **Accuracy**: Correctness of information +5. **Validation**: Proper evidence of testing and validation + +### Review Timeline + +- **Initial review**: Within 2-3 business days +- **Follow-up reviews**: Within 1-2 business days after changes +- **Final approval**: After all concerns are addressed + +### Common Review Feedback + +**Frequently Requested Changes:** +- Fix formatting inconsistencies +- Improve content accuracy +- Update documentation quality +- Add missing information +- Clarify PR description or validation evidence + +**PRs That May Be Rejected:** +- Inconsistent formatting +- Missing validation evidence +- Inaccurate or incomplete content +- Insufficient documentation updates +- Poor organization or structure + +## Formatting and Linting + +- **You must address all feedback from automated bots** (e.g., text linters, formatting bots) as you would human reviewers. +- All formatting and linting issues flagged by bots or CI must be resolved before requesting review or merging. +- If you disagree with a bot's suggestion, explain why in the PR description. +- If a bot's feedback is not addressed and a human reviewer must repeat the request, the PR will be closed until all automated feedback is resolved. + +## Text File Best Practices + +### Content Guidelines + +- Use clear, descriptive language +- Include appropriate examples where helpful +- Follow established content patterns +- Ensure accuracy and completeness +- Update content when related code changes + +### Organization Guidelines + +- Use consistent structure and formatting +- Implement proper organization and hierarchy +- Maintain readability and clarity +- Use appropriate headers and sections +- Follow established naming conventions + +### Configuration Guidelines + +- Use consistent formatting and structure +- Follow established naming conventions +- Ensure proper validation and error handling +- Document configuration options clearly +- Maintain backward compatibility where possible + +## Code of Conduct + +This project adheres to the [Contributor Covenant Code of Conduct](CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. \ No newline at end of file diff --git a/.github/instructions/xml.instructions.md b/.github/instructions/xml.instructions.md new file mode 100644 index 000000000..fe24a48d0 --- /dev/null +++ b/.github/instructions/xml.instructions.md @@ -0,0 +1,340 @@ +--- +applyTo: '**/*.xml' +--- + +# XML File Instructions (Quick Reference) + +- **Read this file before editing any .xml file** +- **Cross-reference with related instruction files** +- **Complete the Validation Checklist before submitting** +- **Stop and request help if uncertain** + +## Context Loading for Copilot + +When working on this file type, you MUST: +1. Read this entire instruction file before making any changes +2. Cross-reference with related instruction files (listed below) +3. Validate your understanding by checking the "Validation Checklist" section +4. If uncertain about any requirement, stop and request clarification + +**Related Instruction Files:** +- [project.instructions.md](project.instructions.md) - For project and build configuration +- [csharp.instructions.md](csharp.instructions.md) - For C# code changes +- [text.instructions.md](text.instructions.md) - For plain text documentation + +## Validation Checklist + +Before submitting any changes, verify: + +**XML Quality & Documentation:** +- [ ] XML syntax is valid +- [ ] Schema compliance is maintained +- [ ] Documentation is updated +- [ ] Changes work as expected + +**Process:** +- [ ] Conventional commit format used +- [ ] PR description includes validation evidence +- [ ] All checklist items completed +- [ ] No breaking changes introduced (or documented if necessary) + +## Decision Trees + +### When to Request Human Review +- Is this a new XML schema or documentation standard? β†’ Yes β†’ Request expert guidance +- Is this a breaking change to XML structure or documentation? β†’ Yes β†’ Document thoroughly and request review +- Are you uncertain about XML schema or documentation? β†’ Yes β†’ Stop and request guidance + +### When to Stop and Ask for Help +- Uncertain about XML requirements +- Major changes to project configuration +- Security or legal implications + +## Common Mistakes to Avoid + +**DO NOT:** +- Skip validation steps +- Submit changes without validation evidence + +**ALWAYS:** +- Read the entire instruction file first +- Validate all XML and documentation changes +- Include comprehensive documentation updates +- Document all changes thoroughly + +## Context Management + +**Before Starting:** +- Read the complete instruction file +- Understand the current file's purpose and structure +- Identify all related files that may need updates + +**During Editing:** +- Keep track of all changes made +- Validate each change against requirements +- Maintain consistency with existing patterns + +**After Completing:** +- Review all changes against the validation checklist +- Ensure all requirements are met +- Prepare comprehensive PR description with evidence + +## Handling Uncertainty + +**Stop and Request Help When:** +- You cannot explain your approach clearly +- You're making "educated guesses" about XML or documentation +- You're uncertain about project configuration +- You cannot trace the logic in XML without narration + +**Escalation Process:** +1. Stop all work immediately +2. Document what you were trying to accomplish +3. Explain what specific aspect is unclear +4. Request expert guidance with specific questions +5. Do not proceed until you have clear, confident understanding + +## Success Criteria + +Your changes are successful when: +- All XML and documentation validation checks pass +- PR description is complete and accurate +- All checklist items completed +- No automated bot feedback ignored + +## XML Standards + +### XML Formatting Requirements + +- Use consistent indentation (2 spaces recommended) +- Follow XML schema standards where applicable +- Ensure valid XML syntax +- Use descriptive element and attribute names +- Maintain consistent structure across similar files + +### XML File Types in Repository + +This repository contains several types of XML files: + +1. **Project files** - MSBuild project configurations +2. **Documentation files** - XML documentation for APIs +3. **Configuration files** - Various configuration settings +4. **Resource files** - Localization and resource management + +## Documentation Standards + +### XML Documentation Requirements + +**Required for all public APIs:** + +- **Use `` tags for all type references** instead of plain text + - βœ… Good: `` or `` + - ❌ Bad: `Task` or `MoqKnownSymbols` +- **Use `` for C# keywords** + - βœ… Good: `` or `` + - ❌ Bad: `true` or `null` +- **Use `` for parameter references** + - βœ… Good: `` + - ❌ Bad: `mockedMemberSymbol` +- **Use `..` for inline code snippets** + - βœ… Good: `x => x.Method()` + - ❌ Bad: `x => x.Method()` + +**Examples:** +```xml +/// +/// Determines whether a member symbol is either overridable or represents a +/// / Result property +/// that Moq allows to be setup even if the underlying +/// property is not overridable. +/// +/// The mocked member symbol. +/// A instance for resolving well-known types. +/// +/// Returns when the member is overridable or is a +/// / Result property; +/// otherwise . +/// +``` + +**Validation:** +- All public APIs must have complete XML documentation +- All type references must use `` tags +- All C# keywords must use `` tags +- Documentation must be accurate and up-to-date + +## Project Configuration + +### MSBuild Project Files + +- Follow MSBuild best practices +- Use consistent property naming +- Maintain proper dependency references +- Ensure build targets are correctly configured +- Use appropriate target framework specifications + +### Configuration Standards + +- Use consistent XML structure and formatting +- Follow established naming conventions +- Ensure proper validation and error handling +- Maintain backward compatibility where possible +- Document configuration changes appropriately + +## Code Quality Standards + +### Required Checks + +Before submitting a PR, ensure your changes pass all quality checks: + +1. **XML Validation**: Ensure valid XML syntax +2. **Schema Compliance**: Follow XML schema where applicable +3. **Formatting**: Use consistent formatting +4. **Documentation**: Update relevant documentation +5. **Testing**: Verify XML changes work as expected + +### XML-Specific Requirements + +- Use consistent indentation and formatting +- Follow XML best practices and standards +- Ensure proper validation and error handling +- Use descriptive element and attribute names +- Maintain consistent structure across files + +## Git Commit Messages + +### Guidelines + +1. **Capitalization and Punctuation**: Capitalize the first word and do not end in punctuation. If using Conventional Commits, remember to use all lowercase. +2. **Mood**: Use imperative mood in the subject line. +3. **Type of Commit**: Specify the type of commit using conventional commit types. +4. **Length**: The first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters. +5. **Content**: Be direct, try to eliminate filler words and phrases. + +### Conventional Commits + +Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +**Types:** +- `feat`: New features +- `fix`: Bug fixes +- `docs`: Documentation changes +- `style`: Code style changes (formatting, etc.) +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `chore`: Maintenance tasks +- `ci`: CI/CD changes +- `perf`: Performance improvements +- `build`: Build system changes + +## Pull Request Guidelines + +### PR Title and Description + +**Title Format:** +Follow conventional commit format: `type(scope): description` + +**Description Requirements:** +1. **Clear summary** of changes +2. **Problem statement** (what issue does this solve?) +3. **Solution description** (how does this solve the problem?) +4. **Validation evidence** (how was this tested?) +5. **Related issues** (link to GitHub issues) +6. **Breaking changes** (if any) + +### Required PR Checklist + +Before submitting a PR, ensure: + +- [ ] XML syntax is valid +- [ ] Schema compliance is maintained +- [ ] Documentation is updated +- [ ] Changes work as expected +- [ ] CI checks pass +- [ ] PR description includes validation evidence + +### Validation Evidence Requirements + +**What Constitutes Validation Evidence:** +- XML validation output +- Schema compliance verification +- Documentation accuracy checks +- Screenshots of successful CI runs +- Manual testing results for XML changes + +**Evidence Format:** +- Include validation logs, screenshots, or links to CI runs +- Provide clear, readable evidence +- Ensure evidence is recent and relevant +- Link to specific test results or validation output + +## Review Process + +### What Maintainers Look For + +Maintainers will review PRs for: + +1. **Code Quality**: Adherence to project standards +2. **XML Accuracy**: Proper XML structure and syntax +3. **Documentation**: Proper documentation updates +4. **Schema Compliance**: Adherence to XML schemas +5. **Validation**: Proper evidence of testing and validation + +### Review Timeline + +- **Initial review**: Within 2-3 business days +- **Follow-up reviews**: Within 1-2 business days after changes +- **Final approval**: After all concerns are addressed + +### Common Review Feedback + +**Frequently Requested Changes:** +- Fix XML syntax errors +- Improve documentation quality +- Update schema compliance +- Add missing validation +- Clarify PR description or validation evidence + +**PRs That May Be Rejected:** +- Invalid XML syntax +- Missing validation evidence +- Schema compliance issues +- Insufficient documentation updates +- Poor formatting or structure + +## Formatting and Linting + +- **You must address all feedback from automated bots** (e.g., XML linters, formatting bots) as you would human reviewers. +- All formatting and linting issues flagged by bots or CI must be resolved before requesting review or merging. +- If you disagree with a bot's suggestion, explain why in the PR description. +- If a bot's feedback is not addressed and a human reviewer must repeat the request, the PR will be closed until all automated feedback is resolved. + +## XML Best Practices + +### Documentation Guidelines + +- Use clear, descriptive text for all documentation +- Include examples where appropriate +- Follow established documentation patterns +- Ensure accuracy and completeness +- Update documentation when APIs change + +### Configuration Guidelines + +- Use consistent naming conventions +- Implement proper validation +- Provide clear error messages +- Maintain backward compatibility +- Document configuration options + +## Code of Conduct + +This project adheres to the [Contributor Covenant Code of Conduct](CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. \ No newline at end of file diff --git a/.github/instructions/yaml.instructions.md b/.github/instructions/yaml.instructions.md new file mode 100644 index 000000000..632691297 --- /dev/null +++ b/.github/instructions/yaml.instructions.md @@ -0,0 +1,332 @@ +--- +applyTo: '**/*.{yml,yaml}' +--- + +# YAML File Instructions (Quick Reference) + +- **Read this file before editing any .yml or .yaml file** +- **Cross-reference with related instruction files** +- **Complete the Validation Checklist before submitting** +- **Stop and request help if uncertain** + +## Context Loading for Copilot + +When working on this file type, you MUST: +1. Read this entire instruction file before making any changes +2. Cross-reference with related instruction files (listed below) +3. Validate your understanding by checking the "Validation Checklist" section +4. If uncertain about any requirement, stop and request clarification + +**Related Instruction Files:** +- [project.instructions.md](project.instructions.md) - For project and build configuration +- [json.instructions.md](json.instructions.md) - For configuration files +- [shell.instructions.md](shell.instructions.md) - For scripts used in workflows + +## Validation Checklist + +Before submitting any changes, verify: + +**Workflow & Security:** +- [ ] YAML syntax is valid +- [ ] All workflow requirements met +- [ ] Security scan completed after dependency changes +- [ ] Performance impact assessed + +**Process:** +- [ ] Conventional commit format used +- [ ] PR description includes validation evidence +- [ ] All checklist items completed +- [ ] No breaking changes introduced (or documented if necessary) + +## Decision Trees + +### When to Request Human Review +- Is this a new CI/CD workflow? β†’ Yes β†’ Request expert guidance +- Is this a breaking change to workflow or security? β†’ Yes β†’ Document thoroughly and request review +- Are you uncertain about workflow or security requirements? β†’ Yes β†’ Stop and request guidance + +### When to Stop and Ask for Help +- Uncertain about workflow or security requirements +- Major changes to CI/CD process +- Security or legal implications + +## Common Mistakes to Avoid + +**DO NOT:** +- Skip validation steps +- Ignore security scanning after dependency changes +- Submit changes without validation evidence + +**ALWAYS:** +- Read the entire instruction file first +- Validate all workflow and security changes +- Include comprehensive documentation updates +- Document all changes thoroughly + +## Context Management + +**Before Starting:** +- Read the complete instruction file +- Understand the current file's purpose and structure +- Identify all related files that may need updates + +**During Editing:** +- Keep track of all changes made +- Validate each change against requirements +- Maintain consistency with existing patterns + +**After Completing:** +- Review all changes against the validation checklist +- Ensure all requirements are met +- Prepare comprehensive PR description with evidence + +## Handling Uncertainty + +**Stop and Request Help When:** +- You cannot explain your approach clearly +- You're making "educated guesses" about workflow or security +- You're uncertain about CI/CD process +- You cannot trace the logic in workflow without narration + +**Escalation Process:** +1. Stop all work immediately +2. Document what you were trying to accomplish +3. Explain what specific aspect is unclear +4. Request expert guidance with specific questions +5. Do not proceed until you have clear, confident understanding + +## Success Criteria + +Your changes are successful when: +- All workflow and security validation checks pass +- Security scan is clean +- PR description is complete and accurate +- All checklist items completed +- No automated bot feedback ignored + +## CI/CD Workflow Requirements + +### Workflow Configuration Standards + +- Use consistent YAML formatting and indentation +- Follow GitHub Actions best practices +- Ensure proper workflow syntax +- Use descriptive job and step names +- Maintain consistent structure across workflows + +### CI Workflow Requirements + +When making CI/CD changes: + +1. **Test locally first**: Ensure workflows run successfully locally +2. **Include validation evidence**: Provide logs or screenshots showing successful execution +3. **Update documentation**: Document new CI features or changes +4. **Consider performance impact**: Ensure changes don't significantly impact CI duration + +### Workflow Validation + +Before submitting CI/CD changes: + +1. **Syntax Validation**: Ensure YAML syntax is correct +2. **Local Testing**: Test workflows locally when possible +3. **Performance Impact**: Assess impact on CI duration +4. **Security Review**: Ensure no security vulnerabilities are introduced +5. **Documentation Update**: Update relevant documentation + +## Performance Testing Guidelines + +### When Performance Testing is Required + +- New analyzers or fixers +- Changes to existing analyzer logic +- Dependency updates that might affect performance +- CI/CD changes that impact build times + +### Performance Testing Process + +1. Run benchmarks locally using `dotnet run --project tests/Moq.Analyzers.Benchmarks/` +2. Compare results against baseline +3. Document any performance regressions or improvements +4. Include benchmark results in PR description + +### Performance Validation Evidence + +- Benchmark output showing no significant regressions +- Comparison with previous baseline results +- Explanation of any performance changes + +## Security Considerations + +### Security Scanning Requirements + +- **All dependency updates require security scanning** +- Run Trivy scan after dependency changes +- Address any security vulnerabilities before merging +- Document security implications in PR description + +### Security Workflow Configuration + +- Configure security scanning in CI/CD workflows +- Set up automated vulnerability detection +- Ensure proper security reporting +- Configure security alerts and notifications + +## Code Quality Standards + +### Required Checks + +Before submitting a PR, ensure your changes pass all quality checks: + +1. **YAML Validation**: Ensure valid YAML syntax +2. **Workflow Testing**: Test workflows locally when possible +3. **Performance Impact**: Assess impact on CI duration +4. **Security Review**: Ensure no security vulnerabilities +5. **Documentation**: Update relevant documentation + +### YAML-Specific Requirements + +- Use consistent indentation (2 spaces recommended) +- Follow YAML best practices +- Ensure proper syntax and structure +- Use descriptive names for jobs, steps, and variables +- Maintain consistent formatting across workflows + +## Git Commit Messages + +### Guidelines + +1. **Capitalization and Punctuation**: Capitalize the first word and do not end in punctuation. If using Conventional Commits, remember to use all lowercase. +2. **Mood**: Use imperative mood in the subject line. +3. **Type of Commit**: Specify the type of commit using conventional commit types. +4. **Length**: The first line should ideally be no longer than 50 characters, and the body should be restricted to 72 characters. +5. **Content**: Be direct, try to eliminate filler words and phrases. + +### Conventional Commits + +Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +**Types:** +- `feat`: New features +- `fix`: Bug fixes +- `docs`: Documentation changes +- `style`: Code style changes (formatting, etc.) +- `refactor`: Code refactoring +- `test`: Adding or updating tests +- `chore`: Maintenance tasks +- `ci`: CI/CD changes +- `perf`: Performance improvements +- `build`: Build system changes + +## Pull Request Guidelines + +### PR Title and Description + +**Title Format:** +Follow conventional commit format: `type(scope): description` + +**Description Requirements:** +1. **Clear summary** of changes +2. **Problem statement** (what issue does this solve?) +3. **Solution description** (how does this solve the problem?) +4. **Validation evidence** (how was this tested?) +5. **Related issues** (link to GitHub issues) +6. **Breaking changes** (if any) + +### Required PR Checklist + +Before submitting a PR, ensure: + +- [ ] YAML syntax is valid +- [ ] Workflows work as expected +- [ ] Documentation is updated +- [ ] Performance impact is assessed +- [ ] Security implications are considered +- [ ] CI checks pass +- [ ] PR description includes validation evidence + +### Validation Evidence Requirements + +**What Constitutes Validation Evidence:** +- YAML validation output +- Workflow execution logs +- Performance benchmark results +- Screenshots of successful CI runs +- Manual testing results for workflow changes + +**Evidence Format:** +- Include logs, screenshots, or links to CI runs +- Provide clear, readable evidence +- Ensure evidence is recent and relevant +- Link to specific test results or validation output + +## Review Process + +### What Maintainers Look For + +Maintainers will review PRs for: + +1. **Code Quality**: Adherence to project standards +2. **Workflow Accuracy**: Proper workflow configuration +3. **Documentation**: Proper documentation updates +4. **Performance**: No significant performance regressions +5. **Security**: No security vulnerabilities introduced +6. **Validation**: Proper evidence of testing and validation + +### Review Timeline + +- **Initial review**: Within 2-3 business days +- **Follow-up reviews**: Within 1-2 business days after changes +- **Final approval**: After all concerns are addressed + +### Common Review Feedback + +**Frequently Requested Changes:** +- Add missing workflow validation +- Update documentation for new workflows +- Improve error handling and logging +- Add performance benchmarks for new workflows +- Clarify PR description or validation evidence + +**PRs That May Be Rejected:** +- Missing validation evidence +- Incomplete workflow testing +- Performance regressions without justification +- Security vulnerabilities +- Insufficient documentation updates + +## Formatting and Linting + +- **You must address all feedback from automated bots** (e.g., YAML linters, formatting bots) as you would human reviewers. +- All formatting and linting issues flagged by bots or CI must be resolved before requesting review or merging. +- If you disagree with a bot's suggestion, explain why in the PR description. +- If a bot's feedback is not addressed and a human reviewer must repeat the request, the PR will be closed until all automated feedback is resolved. + +## Workflow Best Practices + +### GitHub Actions Guidelines + +- Use reusable workflows where appropriate +- Implement proper error handling and retry logic +- Use appropriate triggers for workflows +- Configure proper permissions for jobs +- Use caching to improve performance + +### Workflow Security + +- Use minimal required permissions +- Avoid hardcoding secrets in workflows +- Use GitHub secrets for sensitive information +- Implement proper access controls +- Regular security reviews of workflows + +## Code of Conduct + +This project adheres to the [Contributor Covenant Code of Conduct](CODE-OF-CONDUCT.md). By participating, you are expected to uphold this code. \ No newline at end of file