From 224932dc33c73480ee80096ed30b15fb5ace27a6 Mon Sep 17 00:00:00 2001 From: Bianca Danforth Date: Mon, 27 Nov 2023 12:39:41 -0500 Subject: [PATCH] Update docs to use hyphens when referencing bugs Because: * We have enabled GitHub autolinking[1] in the crash ingestion repos (socorro, tecken, eliot and antenna) * GitHub autolinking doesn't support spaces when pattern matching, so we've added support to rob-bugson (#willkg/rob-bugson#51) to recognize hyphens, and we want to use hyphens when referencing bugs going forward. This commit: * Updates our docs re: conventions when referencing bug ID(s) in git commit subjects and GitHub PR titles * Specifically, this replicates the diff already applied to the Socorro repo in #mozilla-services/socorro#6498 [1]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls#custom-autolinks-to-external-resources --- docs/dev.rst | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/dev.rst b/docs/dev.rst index a464bda8..7d6038a2 100644 --- a/docs/dev.rst +++ b/docs/dev.rst @@ -117,10 +117,14 @@ work to do, note that in the commit. Pull requests ------------- -Pull request summary should indicate the bug the pull request addresses. For +Pull request summary should indicate the bug the pull request addresses. Use a hyphen between "bug" and the bug ID(s). For example:: - bug 1797200: removed frob from tree class + bug-nnnnnnn: removed frog from tree class + +For multiple bugs fixed within a single pull request, list the bugs out individually. For example:: + + bug-nnnnnnn, bug-nnnnnnn: removed frog from tree class Pull request descriptions should cover at least some of the following: @@ -134,7 +138,7 @@ After creating a pull request, attach the pull request to the relevant bugs. We use the `rob-bugson Firefox addon `_. If the pull -request has "bug nnnnnnn: ..." in the summary, then rob-bugson will see that +request has "bug-nnnnnnn: ..." or "bug-nnnnnnn, bug-nnnnnnn: ..." in the summary, then rob-bugson will see that and create a "Attach this PR to bug ..." link. Then ask someone to review the pull request. If you don't know who to ask, look @@ -171,10 +175,13 @@ Conventions Git conventions --------------- -First line is a summary of the commit. It should start with:: +First line is a summary of the commit. It should start with the bug number. Use a hyphen between "bug" and the bug ID(s). For example:: + + bug-nnnnnnn: summary - bug nnnnnnn: summary +For multiple bugs fixed within a single commit, list the bugs out individually. For example:: + bug-nnnnnnn, bug-nnnnnnn: summary After that, the commit should explain *why* the changes are being made and any notes that future readers should know for context or be aware of.