Skip to content

Update copilot-instructions.md PR-linking guidance to prevent cross-repository issues from auto-closing #37533

Description

@wadepickett

Summary

Section 6 ("PR Description Requirements") of .github/copilot-instructions.md instructs Copilot to always put Fixes #[issue-number] on the first line of the PR description. This causes a problem when an issue originates in another repository (for example, an issue assigned to copilot in dotnet/aspnetcore that is fixed with a PR in this docs repo): the Fixes keyword can auto-close an issue that should stay open, or a bare #[issue-number] links to the wrong same-numbered issue in this repository.

We should update the rule so that:

  • Same-repo issues fully resolved by a PR still auto-close (the common, desired default — no author action required).
  • Cross-repo issues link but do not auto-close by default.
  • Cross-repo references are always fully qualified (owner/repo#number) so they link to the correct issue.

Current text (Section 6)

### 6. PR Description Requirements
* [ ] ALWAYS include "Fixes #[issue-number]" in the PR description, at the first line of the description to link back to the original issue
* [ ] Include a clear summary of changes made
* [ ] List all files that were modified with brief descriptions

Problems

  1. Cross-repo auto-close: A closing keyword (Fixes/Closes/Resolves) with a fully-qualified owner/repo#number reference closes the other repository's issue on merge. Many cross-repo issues (e.g., product issues tracked in dotnet/aspnetcore) must remain open.
  2. Wrong-issue links: A bare #[issue-number] for a cross-repo issue resolves to an issue of that number in this repository, linking to the wrong (or nonexistent) issue.
  3. No handling of partial fixes: A PR that only partially addresses a same-repo issue shouldn't close it either.

Proposed replacement for Section 6

### 6. PR Description Requirements
* [ ] On the first line of the PR description, reference the originating issue:
  * [ ] Issue in this repository (`dotnet/AspNetCore.Docs`): use a closing keyword: `Fixes #[issue-number]`
  * [ ] Issue in another repository: use a non-closing, fully-qualified reference so it links without closing: `Contributes to [owner]/[repo]#[issue-number]`
* [ ] Exceptions to the above defaults:
  * [ ] If this PR only partially addresses an issue in this repository, use `Contributes to #[issue-number]` instead of `Fixes`, so the issue stays open.
  * [ ] Only use a closing keyword for an issue in another repository when a maintainer explicitly asks for it, and then use the fully-qualified form: `Fixes [owner]/[repo]#[issue-number]`.
* [ ] Never use a bare `#[issue-number]` for an issue in another repository; the bare form resolves to an issue of that number in this repository and links to the wrong issue. Always use the `[owner]/[repo]#[issue-number]` form for cross-repository references.
* [ ] Include a clear summary of changes made
* [ ] List all files that were modified with brief descriptions

Related file to keep consistent

.github/PULL_REQUEST_TEMPLATE.md currently instructs only Fixes #Issue_Number. Its comment should be updated to match the new guidance so it doesn't reintroduce the cross-repo auto-close behavior.

Notes / scope

  • The docs repo's Copilot instructions apply when the PR is authored in this repo (the cross-repo scenario this fixes). They do not apply when the PR is created in the other repository.
  • Instruction files strongly steer, but don't hard-enforce, agent behavior. If enforcement is desired, consider a follow-up PR status check that validates the first line of the PR description.

Associated WorkItem - 628003

Metadata

Metadata

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions