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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions