git.sr.ht: add section about referencing todo tickets

It is now possible to reference tracker tickets in git commit messages.
Describe how it works.

Signed-off-by: Robin Jarry <robin@jarry.cc>

1 files changed, 87 insertions, 0 deletions

diff --git a/git.sr.ht/index.md b/git.sr.ht/index.md
index 3ca034b..ec281e4 100644
--- a/git.sr.ht/index.md
+++ b/git.sr.ht/index.md
@@ -144,6 +144,93 @@ to send the new version. Update the **patchset revision** field on step two when
 you get there — set it to the number of patchset versions you've sent so
 far.
 
+# Referencing tickets in git commit messages
+
+If your source repository is linked to a [project](../hub.sr.ht/index.md), you
+may interact with [todo.sr.ht](../todo.sr.ht/index.md) tickets via specific git
+commit [trailers](https://git-scm.com/docs/git-interpret-trailers). The trailer
+values must be valid URLs to tickets. Any other value will be ignored.
+A comment will be inserted in the referenced tickets with a back-link to the
+git commit and its original author.
+
+For example, the following commit message:
+
+```
+build: work around gcc 4.2 bug
+
+Fix build with ancient gcc.
+
+Fixes: https://todo.sr.ht/~arkanoid/foobar/666
+Signed-off-by: John Doe <john@doe.io>
+```
+
+Will cause the following change on the referenced issue:
+
+> [~arkanoid](https://sr.ht/~arkanoid) **UNRESOLVED -> FIXED** _9 seconds ago_
+>
+> _John Doe referenced this ticket with commit
+> [badcaca0](https://git.sr.ht/~arkanoid/foobar/commit/badcaca0)_.
+
+<div class="alert alert-info">
+  <strong>Note:</strong>
+  The user pushing the commit must have comment and triage access to the bug
+  tracker, otherwise the trailers will be ignored. The commit author is only
+  used in the inserted comment.
+</div>
+
+<div class="alert alert-warning">
+  <strong>Attention:</strong>
+  Only the last 25 commits will be considered when pushing large series. Any
+  referenced issue in a commit preceding the last 25 will be ignored. If you
+  <i>really</i> need to push more than 25 commits for a single feature, do
+  it in multiple pushes.
+</div>
+
+The following trailers are supported:
+
+## Fixes
+
+If the ticket is unresolved, it will be resolved with the `FIXED` resolution.
+If it is already resolved, only a comment will be inserted.
+
+Example:
+
+```
+build: work around gcc 4.2 bug
+
+Fix build with ancient gcc.
+
+Fixes: https://todo.sr.ht/~arkanoid/foobar/666
+Signed-off-by: John Doe <john@doe.io>
+```
+
+## Implements
+
+If the ticket is unresolved, it will be resolved with the `IMPLEMENTED`
+resolution. If it is already resolved, only a comment will be inserted.
+
+Example:
+
+```
+foo: add support for yaml config files
+
+Implements: https://todo.sr.ht/~arkanoid/foobar/1337
+Signed-off-by: John Doe <john@doe.io>
+```
+
+## References
+
+The ticket status will not be changed, only a comment will be inserted.
+
+Example:
+
+```
+foo: add missing docs for yaml config
+
+References: https://todo.sr.ht/~arkanoid/foobar/1337
+Signed-off-by: John Doe <john@doe.io>
+```
+
 # Attaching files to releases
 
 git.sr.ht allows you to attach files, such as executables (aka binaries), PGP