[git-buildpackage] The most optimal gbp workflow?

[Otto Kekäläinen]

Hi!

Thanks Johannes! I tweaked
https://pad.debian.net/p/Role_model_README.source.md based on your
feedback. Comments below.


> > 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?

Importing both is the most universal way and also the only way to
automatically audit/reveal how the tarball is different from git
contents (or that no difference exists).

> > 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.

Yeah but gbp pq has a lot less friction and overhead compared to
traditional quilt patch management, so it seems like the correct word?

> > ## 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?

Updated wording to explain why the second one is needed too.

> > ## 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

Good idea, added to doc.

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

I wasn't able to test this successfully but here is a minor risk of
remote name mismatch of 'upstream' vs 'upstreamvcs'. I'll try if salsa
tool will accept name alignment patch.

> > 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...

If you adopt this README.source and put it in packages you maintain,
then you can make this 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.

Clarified wording in this section.

> > ## 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.

Clarified wording to say "note latest release tag"

> >     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.

Yes I guess it could go into a postimport hook, but somehow I feel it
is easier for new people to grasp when you list all commands and use
gbp.conf to configure options, not trigger new commands.

> > 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.

Clarified wording to explain that updating upstream and pristine-tar
branches is mechanical and not really the subject of code review.