ca040d77ecCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
116 lines
5 KiB
Markdown
116 lines
5 KiB
Markdown
# Categorization Guide
|
|
|
|
## Category Definitions
|
|
|
|
### What's Changed
|
|
Feature work, bug fixes, API improvements, performance enhancements, and any other user-facing changes. This includes:
|
|
- New API surface area (new types, methods, properties)
|
|
- Bug fixes that affect runtime behavior
|
|
- Performance improvements
|
|
- Breaking changes (these appear in both "Breaking Changes" and "What's Changed")
|
|
- Changes that span code + docs (categorize based on the primary intent)
|
|
|
|
### Documentation Updates
|
|
PRs whose **sole purpose** is documentation. Examples:
|
|
- Fixing typos in docs
|
|
- Adding or improving XML doc comments (when not part of a functional change)
|
|
- Updating conceptual documentation (e.g., files in `docs/`)
|
|
- README updates
|
|
- Adding CONTRIBUTING.md or similar guides
|
|
|
|
**Important**: A PR that changes code AND updates docs should go in "What's Changed" — only pure documentation PRs belong here. However, documentation PRs should still be studied during the breaking change audit, as they may document changes that were not properly flagged as breaking.
|
|
|
|
### Repository Infrastructure Updates
|
|
PRs that maintain the development environment but don't affect the shipped product or test coverage. Examples:
|
|
- Version bumps (`Bump version to X.Y.Z`)
|
|
- CI/CD workflow changes (GitHub Actions updates)
|
|
- Dependency updates from Dependabot
|
|
- Build system changes
|
|
- Dev container or codespace configuration
|
|
- Copilot instructions updates
|
|
- NuGet/package configuration changes
|
|
|
|
**Important**: PRs that touch the `tests/` folder should never be categorized as Infrastructure — they belong in either "Test Improvements" or "What's Changed" depending on whether product code was also modified.
|
|
|
|
### Test Improvements
|
|
PRs focused on test quality, coverage, or reliability. Examples:
|
|
- Adding new tests (unit, integration, regression, conformance)
|
|
- Fixing broken or incorrect tests
|
|
- Addressing flaky tests (timing, race conditions)
|
|
- Unskipping or skipping tests
|
|
- Test infrastructure improvements (new test helpers, test base classes)
|
|
|
|
**Important**: PRs that reference "MCP conformance tests" are not automatically test-only. Examine the PR body and file changes to determine whether product code was modified to achieve conformance — if so, the PR belongs in "What's Changed." Conformance PRs should never be placed in "Repository Infrastructure Updates."
|
|
|
|
## Entry Format
|
|
|
|
Use this simplified format (GitHub auto-links `#PR` and `@user`):
|
|
```
|
|
* Description #PR by @author
|
|
```
|
|
|
|
For PRs with co-authors (harvested from `Co-authored-by` commit trailers):
|
|
```
|
|
* Description #PR by @author (co-authored by @user1 @user2)
|
|
```
|
|
|
|
For Dependabot PRs, do not acknowledge @dependabot[bot]:
|
|
```
|
|
* Bump actions/checkout from 5.0.0 to 6.0.0 #1234
|
|
```
|
|
|
|
For direct commits without an associated PR (e.g., version bumps merged directly to the branch), use the commit description and `by @author` but omit the `#PR` reference:
|
|
```
|
|
* Bump version to v0.1.0-preview.12 by @halter73
|
|
```
|
|
|
|
For Copilot-authored PRs, identify who triggered Copilot using the `copilot_work_started` timeline event on the PR. That person becomes the primary author, and @Copilot becomes a co-author:
|
|
```
|
|
* Add trace-level logging for JSON-RPC payloads #1234 by @halter73 (co-authored by @Copilot)
|
|
```
|
|
|
|
## Sorting
|
|
|
|
Sort entries within each section by **merge date** (chronological order, oldest first).
|
|
|
|
## Examples from Past Releases
|
|
|
|
### What's Changed (format example)
|
|
```
|
|
* Add Trace-level logging for JSON-RPC payloads in transports #1191 by @halter73 (co-authored by @Copilot)
|
|
* Use Process.Kill(entireProcessTree: true) on .NET for faster process termination #1187 by @stephentoub
|
|
* Include response body in HttpRequestException for transport client errors #1193 by @halter73 (co-authored by @Copilot)
|
|
* Fix race condition in SSE GET request initialization #1212 by @stephentoub
|
|
* Fix keyset pagination with monotonic UUIDv7-like task IDs #1215 by @halter73 (co-authored by @Copilot)
|
|
* Add ILoggerFactory to StreamableHttpServerTransport #1213 by @halter73 (co-authored by @Copilot)
|
|
* Add support for message-level filters to McpServer #1207 by @halter73
|
|
* Add `DistributedCacheEventStreamStore` #1136 by @MackinnonBuck
|
|
```
|
|
|
|
### Documentation Updates (format example)
|
|
```
|
|
* Fix typo in elicitation.md #1186 by @ruyut
|
|
* Fix typo in progress.md #1189 by @ruyut
|
|
* Clarify McpMetaAttribute documentation scope #1242 by @stephentoub (co-authored by @Copilot)
|
|
```
|
|
|
|
### Repository Infrastructure Updates (format example)
|
|
```
|
|
* Bump version to 0.8.0-preview.1 #1181 by @stephentoub (co-authored by @Copilot)
|
|
* Bump actions/checkout from 6.0.1 to 6.0.2 #1173
|
|
* Bump the opentelemetry-testing group with 6 updates #1174
|
|
```
|
|
|
|
### Test Improvements (format example)
|
|
```
|
|
* Remove 10 second wait from docker tests #1188 by @stephentoub
|
|
* Fix Session_TracksActivities test #1200 by @stephentoub
|
|
* Add serialization roundtrip tests for all Protocol namespace types #1289 by @stephentoub (co-authored by @Copilot)
|
|
```
|
|
|
|
### Acknowledgements (format example)
|
|
```
|
|
* @ruyut made their first contribution in #1186
|
|
* @user submitted issue #1234 (resolved by #5678)
|
|
* @user1 @user2 @user3 reviewed pull requests
|
|
```
|