If lots of people are already using git-debpush then we are effectively
storing git workflow information for a lot of packages in their git
histories.  So it would be good to make that information readily
accessible.  If the last upload was done with --quilt=gbp, then
'git debpush --which-workflow' could print 'gbp'.

I know we call these quilt modes, but people would probably find
something with 'workflow' in it easier to remember.

Sean Whitton writes ("Bug#1078016: git-debpush: want some option to print workflow, if known"):

I agree with this in principle.  I think we need to be a little
careful about the distinctions between

  1. dgit quilt mode
  2. git branch and tree format
  3. workflow

These go from least to most specific.  The user probably needs to know
2, not 1 or 3.  For example, what if the package is maintained in
git-debrebase ?

We lack a good name for 2 but maybe we could fudge it and say
"workflow" when we mean "workflow indistinguishability class under
external examination".

Ian.

Hello,

Yeah, good, we do indeed want to provide (2), and (3) is a matter for
README.source.  So, perhaps this thing ought to be printing "unknown" if
there's the possibility of gdr, for example.

On Wed, 14 Aug 2024 08:28:08 +0800 Sean Whitton <spwhitton@spwhitton.name> wrote:

Hi

Just adding my two (and half) cents on this as I was requesting this
feature.

I want all of this to be machine readable if it is something a user or
packager need to know about. For me, it is only a question of how to
expose this.

Ideally, we would have a single well-defined workflow. However, we, as a
project, have continuously failed to agree on such a workflow and I
doubt we will soon. Therefore, in my "fallback ideal" world, I want to
have tool assistance here.

It should be something like:

     $ git clone .../my-project
     $ cd my-project
     $ explain-packaging-workflow
     Tools and policies specific to this package:

       * `gbp dch` to generate the changelog.
         Documentation: `man:gbp-dch(1)

       * Upload via `dgit push-source` or `dgit push-built`
         Documentation: `man:dgit-maint-debrebease(7)

       * The git workflow uses `dgit`'s `debrebase` and `quilt-mode=...`.
         Documentation: `man:dgit-maint-debrebease(7)

       * The repo uses DEP-14 branch layout
         Documentation: `https://dep.debian.net/deps/dep14`

       * Automatic reformatting of packaging files via `debputy reformat`
         Documentation: `man:debputy(1)`

       * The packaging aims at zero-change rebuild compatibility with
         Debian `${RELEASE}-backports` and Ubuntu `$RELEASE_NAME`

       * The package is a part of the Python packaging team.
         Documentation: `https://....debian.org/python-policy/`

       ...

With the goal of making the "common" cases for `debian/README.source`
obsolete. Then add UX features like highlighting based which rules the
packager has marked as "known" vs. rules they do not know, etc.

Obviously, I do not expect `dgit` to provide said tool nor all the
information here. But the parts under `dgit`'s domain should be machine
readable to enable us to write such a tool.


Ideally, I want this to be reverse engineer-able or machine discoverable
rather than maintained by hand. That is because hand-maintained policies
tend to get out of date as the team changes policies, while reverse
engineering from the data looks at the current pattern. That said, I
fully appreciate that some things are hard or even impossible to
accurately reverse-engineer the common use-cases.

I hope that explains the context and scope for what I want machine
readable. You are the domain experts for `dgit`, so you are in the best
position to say what can and cannot be reversed engineered vs. what must
be a "manually maintained" policy.

Best regards,
Niels

Niels Thykier writes ("Bug#1078016: git-debpush: want some option to print workflow, if known"):

FTR, I think your aims are laudable.  I hope we can help you build
the tool you want.  I wouldn't be surprised if we wanted `dgit clone`
to invoke it :-), eventually.

The situation is complex, though, because there isn't really such a
thing as "the workflow for a package".  Different people can interact
with the same package in different ways, depending on their views,
status, tooling preferences, team policy, and so on.

To give some examples:

 * Some packages are "maintained in dgit".  That means that as a
   matter of policy, any maintainer upload must be done with dgit.

   So whether to upload with dgit can be a decision for the uploader.

 * When doing an NMU, or maintaining a downstream, one might use the
   patches-applied view of the package (dgit fetch, or ad-hoc imported
   apt source).  In that case one can't do a new upstream version, but
   one can do all other changes.  One can then ignore the maintainer's
   git (or quilt or whatever) workflows.

   Note that the *same package* is typically available both as a
   patches-applied view, and as a maintainer git branch possibly in a
   tooling-specific format (eg, gbp pq unapplied).

   So whether to use gbp pq or git-debrebase or whatever can
   be a decision for the user/uploader, and cannot be inferred from
   the contents of the package's filesystem tree, even if one has a
   git repo.  It can sometimes be inferred from git branch structure
   and git tags.  More on this later.

Your examples are illuminating:

These are examples of maintainer (team) policies.  They *must* be
followed when doing a maintainer or team upload.  A kind NMUer will
follow them if it's not too inconvenient.

A user or other downstream may find this information about Debian's
practices useful, but it cannot be relied on (because NMUs) and the
downstream does not need to honour it (because they're outside the
bailiwick of the policy).

This is another team policy question, but it's more subtle.

dgit is explicitly designed to enable dgit-based uploads (eg, NMUs)
even when the maintainer doesn't know or care about dgit.
A non-maintainer dgit split git view upload (eg an NMU) is barely
detectable other than by use of dgit.

It is the opinion of the dgit maintainers that all uploads should be
done with dgit (where possible - eg right now security uploads can't
be).

So the two possible policies for a package are:

 (i) it is the maintainer (team) policy that dgit should be used
 (ii) dgit may be used at the uploader's discretion

One could try to infer the team policy by looking at the last upload.
But there are even mixed teams where some maintainers upload with dgit
and some without.

These also examples of team policies.

But they'r eones which must also be followed (or at least respected)
by NMUers.

This information is specific to the *particular git history* of the
tree being worked with.  I think it can usually be inferred from git
tags if dgit (or, soon, tag2upload) was used to upload.

But this information cannot be inferred from the tree contents.

It is useful for anyone working with the maintainer git view.

IMO non-Debian-experts ought not to work with the maintainer git view,
so we need to take some care about this.   A tool which
unconditionally prints information which is relevant only to the
maintainer tree might print information which is confusing, or even
hazardous, to a Debian-naive user working with a patches-applied view
from `apt source && git add` or `dgit clone`.

OTOH, for a Debian expert this information is invaluable.  If you are
familiar with the relevant tooling you can go right ahead and Do Stuff.
In particular, you know that it's safe to ignore the crazy gbp runes
which often the maintainer put in README.source a decade ago.

So ideally I think the branch status would be inferred from git tags.
git-debpush has some code to do this IIRC but I haven't looked at it
in a while and it may not be 100% reliable.  I forget the details,
but I think Sean knows more.

This is information about the specific repository.  The repo itself is
named in Vcs-Git so the information could be in-tree if it's
understood as only applying to that specific tree.

Obviously a downstream, or even some team member's own fork on salsa,
might have a different layout.

Yes.  The quilt mode is machine-readable in the git tags.

Right.

This makes sense.

I'm afraid this reply may be a bit inchoate (and too long) but I hope
this it's helpful.

Ian.

Hello,

Right, yeah, that is the component of this that this bug is about.
It's reliable up to what tag2upload needs to know about the branch
format for it to successfully construct an upload.  As Ian says, how
that maps onto what a human might want to know is a bit more subtle.

I think Niels's explain-packaging-workflow is a good idea, doable, and
that this bug's feature request would contribute to it.
Thanks for posting!