Package: developers-reference
Version: 14.18
Severity: wishlist
Tags: patch

Dear maintainers,

The general resolution of August 2026 on generative AI left the
practice to each contributor, and section 7.1 (Bug reporting) is where
a reporter looks for that practice. It does not yet say what makes a
report prepared with such a tool one a maintainer can act on.

I report bugs to Debian with AI assistance, and I learned these habits
on Debian's own tracker:

- #1152863 (snmptt): reproduced in a clean container, the one-line
  patch inline. It was fixed in 1.5-4 about an hour later.
- #1152488 (openssl): the maintainer asked for a patch, and it went
  into 4.0.3+really4.1.0-1.
- #1152864 (pkcs11-daemon): closed as not a bug. I had read a default
  in a configuration file as a missing dependency. The maintainer was
  right, and the fourth point of the patch is that lesson.

The attached patch adds section 7.1.2 with eight short points: search
first, reproduce the problem yourself, do not claim an absence from a
search of the source, find out what the maintainer intends, send the
fix as a tested patch, one problem per report, understand and answer
for every line, and one report per package. It comes after the mass
bug filing section, so that 7.1.1, which the resolution cites, keeps
its number.

I built the manual from git (1510f34) with and without the patch
(sphinx-build, html): the same single warning both times, and the new
section rendered with its two links.

The wording is yours to change.

The same habits, written as instruction files that AI coding tools
read before they work, are public at
https://github.com/Sparky-OS/sparky-stereo-os/tree/main/skills/contrib-debian
in case they are useful to others who report with such tools.

I wrote this report and the patch with AI assistance and checked both
myself.

Daniel Ramos

--- the patch, against git 1510f34 ---

diff --git a/source/beyond-pkging.rst b/source/beyond-pkging.rst
index aca438b..98cfabe 100644
--- a/source/beyond-pkging.rst
+++ b/source/beyond-pkging.rst
@@ -120,6 +120,49 @@ describing your intention there.
 To view bugs tagged with a specific usertag, visit
 ``https://bugs.debian.org/cgi-bin/pkgreport.cgi?users=``\ *email-addr*\ 
``&tag=``\ *tag-name*.
 
+.. _submit-bug-assisted:
+
+Reports and patches prepared with AI assistance
+--------------------------------------------------------------------------------------------------------------------------------
+
+The project's `statement on the responsible use of generative
+AI <https://www.debian.org/vote/2026/vote_002>`__ holds an assisted
+contribution to the same standards as any other, and leaves the
+responsibility with the person who submits it. For a bug report, these
+habits are what make such a report one a maintainer can act on:
+
+-  Search before reporting: the package's open and closed bugs, its
+   newer version in unstable, its packaging repository (the ``Vcs-Git``
+   field of the source) and upstream. A fix that already exists is not
+   reported again.
+
+-  Reproduce the problem yourself, in a clean chroot or container of
+   the suite you report against, with Debian's own package installed.
+   Say in the report what you ran and what you only read.
+
+-  Do not report that a program lacks or ignores something because a
+   search of its source found nothing. Run the program.
+
+-  Find out what the maintainer intends before calling a behaviour a
+   bug: read ``README.Debian``, the changelog and the package's closed
+   bugs. A default in a configuration file that the administrator is
+   meant to adapt is not a missing dependency.
+
+-  When you propose a fix, send it as a patch against Debian's own
+   source (``apt-get source``), inline in the report, with the
+   ``patch`` tag, and show the same test failing before it and passing
+   after it.
+
+-  One problem per report, with the exact messages. Choose the severity
+   from Debian's definitions, not from the tool's own rating.
+
+-  Read, understand and be ready to explain every line you send, and
+   answer follow-up questions yourself. Disclosing the assistance is
+   encouraged; saying it once in the report is enough.
+
+-  The same fault in several packages is still one report per package;
+   for many packages, see :ref:`submit-many-bugs` first.
+
 .. _qa-effort:
 
 Quality Assurance effort


-- System Information:
Debian Release: forky/sid
  APT prefers testing
  APT policy: (500, 'testing')
Architecture: amd64 (x86_64)

Kernel: Linux 7.3.4-stereo3d18 (SMP w/12 CPU threads; PREEMPT)
Kernel taint flags: TAINT_WARN, TAINT_OOT_MODULE, TAINT_UNSIGNED_MODULE
Locale: LANG=C, LC_CTYPE=C.UTF-8 (charmap=UTF-8), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: unable to detect

developers-reference depends on no packages.

Versions of packages developers-reference recommends:
pn  debian-policy            <none>
pn  libjs-jquery             <none>
pn  libjs-sphinxdoc          <none>
ii  sensible-utils           0.0.26
pn  sphinx-rtd-theme-common  <none>

Versions of packages developers-reference suggests:
pn  doc-base                   <none>
pn  firefox-esr | www-browser  <none>

-- no debconf information

Reply via email to