Skip to content

docs: add PR issue closing syntax guidance #252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
joshsmithxrm merged 1 commit into from
Jan 7, 2026
Merged

docs: add PR issue closing syntax guidance #252

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
3 changes: 2 additions & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ NuGet packages & CLI for Power Platform: plugin attributes, Dataverse connectivi
| Implement data/business logic in UI layer | UIs are dumb views; logic belongs in Application Services |
| Write progress directly to console from services | Accept `IProgressReporter`; let UI render (ADR-0025) |
| Throw raw exceptions from Application Services | Wrap in `PpdsException` with ErrorCode/UserMessage (ADR-0026) |
| Use comma-separated issues in `Closes` | GitHub only auto-closes first; use separate `Closes #N` lines |

## ALWAYS

Expand All @@ -32,7 +33,7 @@ NuGet packages & CLI for Power Platform: plugin attributes, Dataverse connectivi
| Accept `IProgressReporter` for operations >1 second | All UIs need feedback for long operations (ADR-0025) |
| Include ErrorCode in `PpdsException` | Enables programmatic handling (retry, re-auth) (ADR-0026) |
| Make new user data accessible via `ppds serve` | VS Code extension needs same data as CLI/TUI |
| Link related issues in PR body | Use "Closes #123" or "Relates to #456" |
| Link related issues in PR body | Use separate `Closes #N` per issue; comma syntax only closes first |
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Jan 7, 2026

Choose a reason for hiding this comment

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

medium

The new NEVER rule on line 23 is a great addition and clearly explains the anti-pattern.

For this ALWAYS rule, the updated explanation becomes slightly redundant with the NEVER rule. It also loses the generality of the original guidance, which included non-closing keywords like Relates to.

To improve clarity and conciseness, I suggest a version that incorporates both aspects: general linking and the specific instruction for closing multiple issues. This approach keeps the detailed failure case (comma syntax only closes first) in the NEVER table, where it's most impactful, avoiding repetition.

Suggested change
| Link related issues in PR body | Use separate `Closes #N` per issue; comma syntax only closes first |
| Link related issues in PR body | Use `Closes #N` or `Relates to #N`. For multiple issues, use separate `Closes #N` lines. |
References
  1. When documenting principles, prefer conciseness. Avoid adding redundant text if the existing wording already captures the essence of the principle, even if it's less explicit.
  2. For documentation intended for an AI reader, prioritize concise, directive phrasing that is consistent with existing formats over separating patterns from their rationale.

| Use JSON for config files, JSONL for streaming | No YAML; consistency with CLI output (ADR-0016) |

---
Expand Down