diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9495a5d..06a9dda 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,11 +14,72 @@ contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additio ## How to Contribute -1. Fork the repository -2. Create a feature branch (`git checkout -b my-feature`) -3. Make your changes -4. Run tests and ensure the build passes -5. Submit a pull request +This repository accepts pull requests, but not every type of change should start as a pull request. + +### Changes That Usually Do Not Need Prior Approval + +Small, scoped pull requests are generally welcome without prior discussion when they: + +- Fix a clear bug +- Correct typos, broken links, or other documentation issues +- Add or improve tests for existing behavior +- Make low-risk maintenance changes that do not change product direction, architecture, or user experience + +These changes should still be focused, easy to review, and aligned with the existing codebase. + +### Changes That Require Prior Approval + +Please do not open a pull request first for changes such as: + +- New features or user-visible capabilities +- Large refactors or architectural changes +- Changes to public behavior, workflows, or UI patterns +- Significant dependency changes +- Broad performance, telemetry, or security-related changes that affect product direction + +These kinds of changes need review and guidance from the Microsoft team responsible for the product roadmap and design direction. + +### Proposal First for Larger Changes + +If you want to propose a new feature or substantial change, start a GitHub Discussion in the `Ideas` category instead of opening a pull request immediately. + +Your proposal should briefly cover: + +- The problem you are trying to solve +- Why the current behavior is insufficient +- The user impact and expected benefit +- A rough implementation approach, if relevant +- Alternatives you considered + +When you believe the discussion is ready for formal consideration, add the `design review` label. That label means a design review is requested. It does not mean the proposal has been approved. + +The team may: + +- Approve the proposal +- Decline the proposal +- Request changes to the scope or design +- Meet with the author to refine the design +- Decide to implement it internally +- Mark it as open for a community contribution + +When a design is under review a corresponding issue will be opened for it that will track the proposal's progress. +The issue may also revise the proposal or add detail for implementation. + +Only after that process has resulted in an "open for contribution" status, should a pull request be opened. + +### Pull Request Process + +1. Fork the repository. +2. If the change is more than a small bug fix or documentation update, open a GitHub Discussion in `Ideas` first and wait for guidance. +3. If you are proposing a larger change, use the `design review` label when you are requesting formal design consideration. +4. If the design is accepted, wait for a member of the Microsoft design team to create the corresponding GitHub Issue for implementation tracking. +5. Create a branch for the approved or clearly scoped change. +6. Make the smallest change that fully addresses the issue. +7. Run relevant tests and ensure the build passes. +8. Update documentation when behavior or workflows change. +9. Submit a pull request with a clear description of the problem, approach, and validation. + +If a pull request arrives without prior discussion for a change that needs design or roadmap approval, it may be closed and redirected to Discussions. ## Development Setup @@ -80,3 +141,4 @@ When reporting a bug, please include: - Follow existing code style and conventions - Update documentation if needed - Ensure the build passes before submitting +- Link the relevant GitHub Discussion when prior approval was required