diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9cfd1f6 --- /dev/null +++ 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 / +``` + +**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 + : + + [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 + +``` + +**Example**: + +```markdown + +``` + +### 4. Submit a Pull Request + +1. **Push your branch**: `git push origin /` +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 index 8f40a13..8d37e94 100644 --- 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 index 7ed8817..3155d06 100644 --- 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: