[git-buildpackage] The most optimal gbp workflow?

[Johannes Schauer Marin Rodrigues]

Hi,

Quoting Otto Kekäläinen (2024-12-03 21:25:49)
> (Moving discussion to mailing list)

thank you for keeping me in the loop. I'm not subscribed to
git-buildpackage at lists.sigxcpu.org so keep me CC-ed if you like. Thank you. :)

> I am trying to write the definitive most optimal workflow
> documentation for git-buildpackage. Initially I am doing it in the
> context of this package:
> * https://salsa.debian.org/debian/j4-dmenu-desktop/-/blob/debian/latest/debian/gbp.conf
> * https://salsa.debian.org/debian/j4-dmenu-desktop/-/blob/debian/latest/debian/README.source.md
> 
> I however intend to generalize it later. The settings in the gbp.conf
> are probably already pretty optimal, so I am seeking comments on what
> you think about the README.source?
> 
> Live version is now at
> https://pad.debian.net/p/Role_model_README.source.md to more easily
> keep track what is the most optimal version during this discussion.
> 
> Starting point with latest updates today is below for convenience so
> people reading email offline can see it right away:
> 
> *****************************************************
> 
> # README for Debian package maintainers and contributors
> 
> This Debian packaging source code in directory `debian/` is maintained on branch
> `debian/latest` (naming following DEP14)

I think we just had another very large thread on d-devel about DEP14 versus
DEP-14 versus DEP 14? ;)

> The command above also automatically adds the upstream repository as an extra
> remote, and fetches the latest upstream `develop` branch commits and tags. The
> upstream development branch is not a requirement to build the Debian package,
> but is recommended for making collaboration with upstream easy.

I was recently told in another thread on d-devel@ that using mode=git is
supposedly the way to go for uscan. In case of j4-dmenu-desktop, we now have
upstream's git repository locally and upstream gpg-signs every commit. Why
would we not also use the git repository directly for importing new upstream
releases? Why does that repo still go through the release tarball?

> The repository structure and use of `gbp pq` makes it easy to cherry-pick
> commits between upstream and downstream Debian, ensuring improvements downstream
> in Debian and upstream in the original project are shared frictionlessly.

Well... with "less friction". Your use of the adverbs "simply", "easily" or
"frictionlessly" sometimes makes me think like I'm reading an advertisement
instead of documentation. For my taste, the wording could be a bit more
neutral.

> ## Updating an existing local git repository
> 
> If you have an existing local repository created in this way, you can update it
> by simply running:
> 
>     gbp pull
> 
> To also get the upstream remote updated run:
> 
>     git pull --all --verbose

But if I run the latter, it will also do the job of the former, no? So why run
the former if doing the latter is sufficient?

> ## Contributing to the Debian packaging
> 
> First clone the Debian packaging repository using git-buildpackage as described
> above. Then open https://salsa.debian.org/debian/j4-dmenu-desktop and press
> "Fork". This is needed for Salsa to understand that your repository has the same
> origin.

Should we not recommend the "salsa" tool instead of clicking buttons in a
browser? As far as I understand it, you could also run:

    $ salsa fork debian/j4-dmenu-desktop --verbose
    $ cd j4-dmenu-desktop

And it will automatically have configured that git clone with remote "origin"
as your fork and remote "upstream" as debian/j4-dmenu-desktop.

> Finally open a Merge Request on salsa.debian.org. If your submission is high
> enough quality, the maintainer is likely to approve it and include your
> improvement in the revision of the Debian package.

Well... While this would be nice, it's not always true...

> The Debian packaging repository will only accept changes in the `debian/`
> subdirectory. Any fix for upstream code should be contributed directly to
> upstream.

Really? What about changes to upstream that we either want to carry temporarily
until they are accepted upstream? What about changes that are not upstreamable?
Those should go into debian/patches and those are fine.

> ## Importing a new upstream release
> 
> To check for new upstream releases run:
> 
>     git fetch --verbose upstreamvcs
>     # Note latest tag, e.g. r3.2, and verify it
>     git verify-tag r3.2
>     # Download upstream release tarball, and merge using both git tag
> and tarball
>     gbp import-orig --uscan

The fact that there is a new tag, does not automatically mean that upstream
made a new release as well.

>     gbp dch --distribution=UNRELEASED \
>       --commit --commit-msg="Update changelog and refresh patches
> after %(version)s import" \
>       -- debian

Should this not go into the gbp postimport hook? Is --distribution=UNRELEASED
really needed? I never passed that to gbp dch and it did the right thing
always.

> Note that git-buildpackage will automatically push all three branches
> (`debian/latest`, `upstream/latest` and `pristine-tar`) and upstream tags to
> your fork so it can run the CI. However, merging the MR will only merge one
> branch (`debian/latest`) so the Debian maintainer will need to push the other
> branches to the Debian packaging git repository manually with `git push`. It is
> not a problem though, as the upstream import is mechanical for the
> `upstream/latest` and `pristine-tar` branches. Only the `debian/latest` branch
> has changes that warrant a review and potentially new revisions.

Really? We do not (yet) carry upstream release hashes, so while it is usually
the case, it is not impossible that the upstream release that person A
downloaded on one day differs from the same release that person B downloaded
the next day.

Thanks!

cheers, josch
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: signature
URL: <http://lists.sigxcpu.org/pipermail/git-buildpackage/attachments/20241203/0de33e5c/attachment.sig>