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. _______________________________________________ git-buildpackage mailing list [email protected] http://lists.sigxcpu.org/mailman/listinfo/git-buildpackage
