feat: Add CONTRIBUTING.md with clear contribution guidelines (#7)

Copilot · pidster · web-flow · commit ef24fed41551 · 2025-10-24T12:29:04.000+01:00
* Initial plan

* feat: Add CONTRIBUTING.md with contribution guidelines

Co-authored-by: pidster &lt;303151+pidster@users.noreply.github.com&gt;

* fix: Add missing whitespace around Markdown lists and code blocks

Co-authored-by: pidster &lt;303151+pidster@users.noreply.github.com&gt;

---------

Co-authored-by: copilot-swe-agent[bot] &lt;198982749+Copilot@users.noreply.github.com&gt;
Co-authored-by: pidster &lt;303151+pidster@users.noreply.github.com&gt;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,290 @@
+# Contributing to GitHub Copilot Template
+
+Thank you for your interest in contributing to this repository! This document provides clear guidelines on what contributions we accept and how to submit them.
+
+## Purpose of This Repository
+
+This repository is an **educational GitHub Template** created by Capgemini's AI & Software Engineering team. It provides practical, portable, and thoroughly documented examples of GitHub Copilot configuration for real-world projects.
+
+**Key Principle**: All prompt content must be thoroughly commented to explain the prompting techniques, design rationale, and expected behaviors.
+
+## What We Accept
+
+We welcome the following types of contributions:
+
+### ✅ New Custom Prompts (Educational Examples Only)
+
+- **Accepted**: New custom prompts, chat modes, or instructions that demonstrate prompting techniques and repository setup patterns
+- **Required**: Comprehensive inline comments explaining:
+  - The prompting technique being demonstrated
+  - Design rationale and reinforcement strategies
+  - Expected behavior and outcomes
+  - Example usage scenarios
+- **Not Accepted**: Generic prompt libraries without educational value or thorough documentation
+
+**Example**: A new chat mode that demonstrates a specific prompting pattern (e.g., chain-of-thought reasoning) with detailed comments explaining how and why it works.
+
+### ✅ Corrections to Existing Configuration/Prompts
+
+- Typo fixes in documentation or prompts
+- Corrections for changes in GitHub Copilot functionality
+- Bug fixes in example code or configurations
+- Clarity improvements in comments or explanations
+
+### ✅ Enhancements to Existing Configuration/Prompts
+
+- Improved prompting techniques with clear documentation
+- Better reinforcement strategies with explanations
+- Additional examples demonstrating edge cases
+- Performance or clarity improvements
+- Enhanced comments and educational content
+
+### ✅ Documentation Enhancements
+
+- Improvements to README files
+- Better explanations of existing features
+- Additional usage examples
+- Clearer architectural documentation
+- Updates to align with current GitHub Copilot features
+
+### ✅ Repository Configuration Enhancements
+
+- Improvements to GitHub Actions workflows
+- Better CI/CD processes
+- Enhanced development tooling
+- Improved repository templates and structures
+
+## What We Don't Accept
+
+### ❌ Undocumented Prompts
+
+Prompts without thorough inline comments explaining the techniques used will not be accepted.
+
+### ❌ Generic Prompt Libraries
+
+This is not a collection of general-purpose prompts. We only accept prompts that serve as educational examples demonstrating specific techniques.
+
+### ❌ Breaking Changes Without Discussion
+
+Major changes to existing configurations should be discussed in an issue before submission.
+
+## How to Contribute
+
+### 1. Before You Start
+
+- **Check existing issues**: Look for related issues or discussions
+- **Review documentation**: Familiarize yourself with the repository structure and existing patterns
+- **Read SSOT files**: Understand the authoritative guidelines in:
+  - `.github/copilot-instructions.md` - Core policies and workflow
+  - `.github/instructions/docs.instructions.md` - Documentation standards
+  - `.github/chatmodes/README.md` - Chat mode authoring guide
+  - `README.md` - Repository overview and SSOT source map
+
+### 2. Create an Issue (Recommended)
+
+For significant contributions:
+
+1. Create an issue describing your proposed contribution
+2. Wait for feedback from maintainers
+3. Proceed once you have general agreement
+
+For minor fixes (typos, small corrections):
+
+- You can proceed directly to creating a pull request
+
+### 3. Development Workflow
+
+Follow the repository's trunk-based development workflow:
+
+#### Branch Creation
+
+Create a feature branch following our naming conventions:
+
+```bash
+git checkout -b <type>/<brief-description>
+```
+
+**Branch Types**:
+
+- `feature/` - New features or enhancements
+- `fix/` - Bug fixes
+- `docs/` - Documentation updates
+- `refactor/` - Code refactoring
+- `test/` - Test additions or modifications
+- `chore/` - Maintenance tasks
+
+**Examples**:
+
+- `feature/add-security-chatmode`
+- `fix/typo-in-developer-mode`
+- `docs/improve-contributing-guide`
+
+#### Making Changes
+
+1. **Keep changes focused**: One logical change per pull request
+2. **Small commits**: Make frequent, small commits with clear messages
+3. **Follow conventions**: Use conventional commit format:
+
+   ```text
+   <type>: <subject>
+   
+   [optional body]
+   
+   [optional footer]
+   ```
+
+**Commit Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+
+**Examples**:
+
+- `feat: Add security-focused chat mode with threat modeling`
+- `fix: Correct typo in Developer.chatmode.md`
+- `docs: Improve explanation of prompting techniques`
+
+#### Adding Comments to Prompts
+
+When creating or modifying prompts, **always include**:
+
+```markdown
+<!--
+PURPOSE: [What this section accomplishes]
+PROMPTING TECHNIQUE: [The technique being demonstrated]
+REINFORCEMENT STRATEGY: [How the instruction is reinforced]
+DESIGN RATIONALE: [Why this approach was chosen]
+-->
+```
+
+**Example**:
+
+```markdown
+<!--
+PURPOSE: Ensure consistent error handling across the codebase
+PROMPTING TECHNIQUE: XML semantic tags for critical requirements
+REINFORCEMENT STRATEGY: 
+1. Bold formatting for emphasis
+2. Concrete examples with ✅/❌ markers
+3. Cross-references to SSOT documentation
+DESIGN RATIONALE: Machine-parseable blocks enable AI to recognize
+non-negotiable requirements while maintaining human readability
+-->
+```
+
+### 4. Submit a Pull Request
+
+1. **Push your branch**: `git push origin <type>/<brief-description>`
+2. **Create PR**: Open a pull request with a clear title matching your branch name format
+3. **Complete PR template**: Fill out all sections of the pull request template
+4. **Link issues**: Reference any related issues using `Fixes #123` or `Closes #456`
+
+#### Pull Request Requirements
+
+Your PR must include:
+
+- **Clear description**: Explain what changed and why
+- **Educational value**: For new prompts, explain what technique is demonstrated
+- **Documentation**: Update relevant README files or documentation
+- **No duplication**: Link to SSOT files instead of duplicating content
+- **Thorough comments**: All prompt content must be well-commented
+- **Small scope**: Keep PRs focused (target ≤ 400 lines when possible)
+
+### 5. Review Process
+
+1. **Automated checks**: Ensure all CI checks pass (markdown lint, link checker, etc.)
+2. **Maintainer review**: At least one maintainer approval required
+3. **Address feedback**: Respond to review comments and make requested changes
+4. **Approval**: Once approved, your PR will be merged
+
+## Code Review Standards
+
+Reviewers will evaluate:
+
+- **Educational quality**: Are prompting techniques well-explained?
+- **Documentation**: Are comments thorough and helpful?
+- **Consistency**: Does the contribution align with existing patterns?
+- **SSOT adherence**: Are references used instead of duplication?
+- **Functionality**: For configurations, do they work as intended?
+
+For detailed review criteria, see `docs/engineering/code-review-guidelines.md`.
+
+## Contribution Types Reference
+
+### Priority Levels
+
+When contributing, consider these priority levels:
+
+- **High**: Corrections to broken functionality, critical documentation fixes
+- **Medium**: Enhancements to existing features, new educational examples
+- **Low**: Nice-to-have improvements, additional documentation
+
+## Getting Help
+
+- **Questions**: Open an issue with the `question` label
+- **Discussions**: Use GitHub Discussions for broader topics
+- **Bugs**: Open an issue with the `bug` label
+- **Feature requests**: Open an issue with the `enhancement` label
+
+## Repository Structure
+
+Familiarize yourself with the repository organization:
+
+```text
+.github/
+├── chatmodes/          # Custom chat mode definitions
+├── instructions/       # Domain-specific instruction files
+├── prompts/            # Reusable prompt templates
+└── workflows/          # GitHub Actions workflows
+
+docs/
+├── ADRs/              # Architectural Decision Records
+├── PRDs/              # Product Requirements Documents
+├── design/            # Design documentation
+└── engineering/       # Engineering guidelines
+
+plans/                 # Project planning documents
+```
+
+## Style Guidelines
+
+### Documentation
+
+- Use clear, concise language
+- Include concrete examples
+- Follow the structure in `.github/instructions/docs.instructions.md`
+- Use proper Markdown formatting
+- Avoid emojis in formal documentation (except in this guide for visual clarity)
+
+### Prompts and Chat Modes
+
+- Include comprehensive HTML comments
+- Explain prompting techniques explicitly
+- Provide both positive and negative examples
+- Use consistent formatting and structure
+- Reference SSOT files instead of duplicating content
+
+### Code Examples
+
+- Follow the language-specific guidelines in `.github/instructions/`
+- Include comments explaining non-obvious logic
+- Provide context for why the example demonstrates the concept
+
+## Attribution
+
+We appreciate all contributors! Your contributions will be recognized in:
+
+- Git commit history
+- Release notes (for significant contributions)
+- GitHub's contributor tracking
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the same license as this repository.
+
+## Questions?
+
+If you have questions about contributing, please:
+
+1. Check this guide and the referenced SSOT documents
+2. Review existing contributions for examples
+3. Open an issue with your question
+
+Thank you for helping make this repository a valuable educational resource!
diff --git a/README.md b/README.md
@@ -143,6 +143,7 @@ When adding new chat modes, prompts, or instructions:
 
 - See `AGENTS.md` for general AI agent instructions and project context
 - See `.github/copilot-instructions.md` for Copilot-specific rules and configuration
+- See `CONTRIBUTING.md` for guidelines on contributing to this repository
 
 ### Copilot Customisation
 
diff --git a/plans/TODO.md b/plans/TODO.md
@@ -42,7 +42,7 @@ How to use:
 | P3-25 | Plan Estimation Checker     | Validate selected estimation model usage                                 | CI script (new)                                                                                              | Plans validated for chosen estimation model consistency                                                                  | Low      | TBD   | Not started |                                                                                                                        |
 | P3-26 | CHANGELOG & Versioning      | Add CHANGELOG and policy version frontmatter                             | `CHANGELOG.md` (new); `.github/copilot-instructions.md`; `*.chatmode.md`                                     | CHANGELOG added; policy version fields present and maintained                                                            | Low      | TBD   | Not started |                                                                                                                        |
 | P3-27 | New Chat Mode Rule          | Enforce: no new chat mode restates templates—must link SSOT              | `.github/chatmodes/README.md`; contribution docs                                                             | Rule documented; referenced in CONTRIBUTING/onboarding docs                                                              | Low      | TBD   | Not started |                                                                                                                        |
-| P3-28 | CONTRIBUTING (Optional)     | Introduce `CONTRIBUTING.md` to consolidate contributor guidance          | `CONTRIBUTING.md` (new)                                                                                      | File added; links to SSOTs; avoids duplication                                                                           | Low      | TBD   | Not started |                                                                                                                        |
+| P3-28 | CONTRIBUTING (Optional)     | Introduce `CONTRIBUTING.md` to consolidate contributor guidance          | `CONTRIBUTING.md` (new)                                                                                      | File added; links to SSOTs; avoids duplication                                                                           | Low      | AI    | Done        | Created comprehensive CONTRIBUTING.md with clear acceptance criteria and workflow guidance                             |
 
 Review checklist mapping:
 
