On Thu, 14 Aug 2025 at 23:00:53 -0600, Antonio Russo wrote:
When I run in to a problem in Debian, I try to follow a rough pattern:
[0. I run into a problem]
1. I identify a suspect package, and diagnose a cause.
2. I identify a solution.
3. I implement the solution, recompile, and confirm it solves the problem.
4. I submit the solution (either upstream or to Debian).
Part of step (4) involves writing prose that documents the investigation
and describes the patch.
Personal opinion, not necessarily shared by everyone:
When someone has identified a problem that can be fixed by patching a
package I maintain, usually the most important piece of information that
I want to see is a solution-neutral problem statement from the step 0
that you didn't include in the list above: "I tried to follow procedure
x, the program did y, but I think it should have done z instead". That
way, I have a basis for assessing whether your diagnosis in step 1 and
the solution from steps 2-4 is actually the most appropriate, or whether
the problem would be better solved in some other way.
For example, I recently did a team upload of devhelp, a GTK GUI program.
If you have found a problem with devhelp, sometimes patching devhelp is
the best course of action, but perhaps it would be more appropriate to
fix a bug in GTK or some other library that it depends on, or perhaps
it's working as intended but your expectation didn't match the design. A
merge request that just changes devhelp's behaviour wouldn't help me to
choose which of those is the right one.
If you're able to propose a solution *as well*, then of course that's
even better - but the more time I spend being an upstream and downstream
maintainer, the more grumpy I get about being asked to reverse-engineer
an observed problem from a proposed solution so that I can do a meaningful
review on the solution.
Debian's canonical way to handle this is that you open a bug with the
solution-neutral problem statement, possibly with a patch attached if
you think you know how to solve it; or, increasingly, people with a
git-centric workflow would prefer to open a bug with the URL of a merge
request. That's fine, either way the bug is an ideal place to put the
problem statement.
Or, if you're confident that your solution is the right one, sometimes
jumping straight to a merge request is OK (if you know that the
maintainer of this particular package will notice MRs), but most of the
time the MR description or commit message does need to indicate what
problem is being solved - otherwise how should I know what problem you
thought you were solving?
This is less important for "cleanup"/"janitorial" changes - if you send
me a patch or merge request that switches from a deprecated dependency
to a non-deprecated one, or says that it silences a Lintian warning, or
something like that, then it's pretty obvious what you were aiming to
achieve. But for bugs (code is functionally wrong in some way), I really
do want to see a description of the problem, not just a solution - and
if you only have time to provide one of those things, usually I'd prefer
the problem description.
There is also the factor mentioned elsewhere in this thread that a
package's maintainer (and particularly the upstream maintainer) probably
has an idea of how they want the code to be designed, and if you charge
ahead with a complicated solution before starting the conversation, you
need to be prepared for the answer to be "thanks, but not that way"
(potentially after you've spent a lot of time on it). If the majority of
the effort is in diagnosing the problem, and the solution is simple,
then that's less likely to be a concern; but if you find yourself
writing relatively complicated code to solve an unreported problem, I
would recommend pausing, reporting the problem, and saying "I'm working
on a fix" before you proceed.
Thanks,
smcv
