Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 67 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Copilot AI Apr 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

GitHub Discussions typically don’t support labels the same way Issues/PRs do (and contributors often can’t apply labels even where labels exist). Consider changing this to an actionable, platform-supported step (e.g., ‘comment to request design review’, ‘use a title prefix like [Design Review]’, or ‘open/convert to an issue and the team will apply the design review label’). The current instruction is likely not executable by contributors.

Suggested change
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.
When you believe the discussion is ready for formal consideration, comment on the discussion to request design review. You may also add a `[Design Review]` prefix to the discussion title to make the request clear. A design review request does not mean the proposal has been approved.

Copilot uses AI. Check for mistakes.

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.

Copilot AI Apr 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is missing punctuation that clarifies the clause boundary. Consider adding a comma after ‘under review’ to improve readability (e.g., ‘When a design is under review, a corresponding issue…’).

Suggested change
When a design is under review a corresponding issue will be opened for it that will track the proposal's progress.
When a design is under review, a corresponding issue will be opened for it that will track the proposal's progress.

Copilot uses AI. Check for mistakes.
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

Expand Down Expand Up @@ -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
Loading