Hello,
DEP-14 is 10 years old and while it's far from being ubiquitous, it
seems to have gained enough traction (in particular in git-buildpackage
thanks to the work of Otto Kekäläinen, and in quite some packaging teams
thanks to the respective team members) that it would be worth marking
it as ACCEPTED.
https://dep-team.pages.debian.net/deps/dep14
But before this, there are a couple of outstanding improvements that
have been suggested where I'd like peer review.
1/ https://salsa.debian.org/dep-team/deps/-/merge_requests/9
(see mr9.patch attached if you don't want to look up on the web)
We had a couple of revisions already and it seems fine to me to merge
this, if anyone has valid objections (i.e. with good rationale), now is
the time to raise them. You might want to look the closed comments
on the above merge request to see whether your concerns have been
discussed already.
This change basically adds the recommendation to use "upstreamvcs" as the
name of the "git remote" to access the upstream repository and it also
documents the possibility to merge the upstream commits in the
"upstream/latest" branch (as proposed by gbp import-orig
--upstream-vcs-tag) when your workflow is to import the upstream tarball.
2/ https://salsa.debian.org/dep-team/deps/-/merge_requests/16
(see mr16.patch attached if you don't want to look up on the web)
This change is still under discussion (no consensus has been reached yet)
but it would be nice to have some broader participation to help bring the
discussion to some conclusion. Basically the topic is how to name the
branches when the package maintainer wants to support multiple upstream
releases for a given target Debian release.
We solved this for the "upstream/*" branches but we never specified this for
the "debian/*" branches partly because Debian doesn't have PPA so it's
rather unusual to maintain multiple upstream releases for the same target
Debian release... but the use case seems like worth supporting and having
a good recommendation for it.
Ideally join the discussion on salsa, but I'll take into account comments
shared here as well. Please cc me preferrably as I don't read debian-devel
daily.
Cheers,
--
⢀⣴⠾⠻⢶⣦⠀ Raphaël Hertzog <hert...@debian.org>
⣾⠁⢠⠒⠀⣿⡁
⢿⡄⠘⠷⠚⠋ The Debian Handbook: https://debian-handbook.info/get/
⠈⠳⣄⠀⠀⠀⠀ Debian Long Term Support: https://deb.li/LTS
diff --git a/web/deps/dep14.mdwn b/web/deps/dep14.mdwn
index a00b019..bd129dd 100644
--- a/web/deps/dep14.mdwn
+++ b/web/deps/dep14.mdwn
@@ -135,6 +135,11 @@ manage different versions of the packages in both repositories, then
the branches `debian/wheezy-security` and `debian/wheezy-updates`
can be used.
+The codename can also be prefixed with the version so that branch names
+are correctly sorted by age of the target release in the list of available
+branches. Examples: `debian/12-bookworm`, `debian/11-bullseye`,
+`ubuntu/24.04-noble`, `ubuntu/22.04-jammy`.
+
Tagging package releases
------------------------
@@ -146,6 +151,28 @@ releasing a package with version 1.3-0ubuntu1 would use
`ubuntu/1.3-0ubuntu1`. The tags should point to the exact commit that was
used to build the corresponding upload.
+Coexistence with the upstream Git repository
+============================================
+
+As a package maintainer, it is often helpful to have access to the
+upstream Git repository from one's personal checkout of the packaging Git
+repository. When setting up access to the upstream repository with `git
+remote add` it is recommended to use `upstreamvcs` as the name of the
+remote so that tools can more easily identify the upstream branches and
+commits.
+
+The naming conventions recommended in this document ensure that names
+of the upstream branches (ex: `master`, `main`, `devel`, `9.x`) are
+unlikely to clash with the packaging branches. Despite this, it is good
+practice to not push any upstream branch to the packaging repository so as
+to not confuse anyone about the purpose of the Git repository.
+
+However to make it convenient to inspect the upstream history and compare
+it to the packaged version, when this doesn't have adverse consequences
+(such as an unreasonable repository size), the upstream history should be
+made available in the packaging repository by pushing the upstream release
+tags alongside with the tags of the packaging branches.
+
Managing upstream sources
=========================
@@ -189,6 +216,40 @@ when needed: for example when it does a release based on a Git snapshot or
when the tag naming scheme used by upstream is not following the above
rules.
+Importing upstream releases when both tarballs and Git tags are available
+-------------------------------------------------------------------------
+
+If upstream publishes both git tags to signify which exact commit was used to
+make a release, and also publishes tarballs that contain a release (which might
+have additional files or have some files removed), the Debian packaging
+repository may include merge commits from the upstream release tags into
+the `upstream/` branch, which in turn should include the unpacked tarball
+contents.
+
+Example git history view:
+
+```
+* 6d6a86 Update changelog for Debian release 5.6-1 (HEAD -> debian/latest)
+* a354baa Packaging change 3
+* 7da232b Packaging change 2
+* 37df28c Packaging change 1
+* f559aeb Update changelog and refresh patches after 5.6 import
+* 22f0227 Update upstream source from tag 'upstream/5.6'
+|\
+| * 67b9260 New upstream version 5.6 (tag: upstream/5.6, upstream/latest)
+| |\
+| | * 3cd8127 Prepare 5.6 release (tag: 5.6, master)
+| | * 2d8e8e6 Upstream commit 3
+| | * a7f1f0c Upstream commit 2
+| | * 1a37e8b Upstream commit 1
+| * | 22a7f43 New upstream version 5.5 (tag: upstream/5.5)
+* | | 983d559 Open new changelog entry
+* | | 1964390 Update changelog for Debian release 5.5-1 (tag: debian/5.5-1)
+| | \ (upstream branch: 'master')
+| \ (Debian branch for tarball imports: 'upstream/latest')
+\ (Debian branch for packaging work: 'debian/latest')
+```
+
About pristine-tar
------------------
@@ -308,3 +369,10 @@ Changes
* For native packages, require the default branch to be a devel branch
* Minor typo fixes and cosmetic changes
* Promote DEP to State: CANDIDATE
+* 2025-01-04:
+ * Specify that stable branches can also have version prefix,
+ e.g `debian/12-bookworm`
+ * Explain the double merge that at least git-buildpackage will do if upstream
+ has both git tags and tarball releases
+ * Recommend `upstreamvcs` as the name of the git remote for the upstream
+ repository
commit 3ad1be1e461c99398312b3faf5353f327a64a974 (HEAD -> mr-16)
Author: Julien Plissonneau Duquène <sre4e...@free.fr>
Date: Sun Jan 5 12:24:56 2025 +0000
Add a section describing package version branches
diff --git a/web/deps/dep14.mdwn b/web/deps/dep14.mdwn
index a00b019..ff9d1be 100644
--- a/web/deps/dep14.mdwn
+++ b/web/deps/dep14.mdwn
@@ -146,6 +146,18 @@ releasing a package with version 1.3-0ubuntu1 would use
`ubuntu/1.3-0ubuntu1`. The tags should point to the exact commit that was
used to build the corresponding upload.
+Maintaining multiple versions of a package
+------------------------------------------
+
+Branches used to work on different versions of a Debian package in the same
+repository should be named following a `<vendor>/<version>/<suite>` scheme
+where `<version>` matches the version number as embedded in the names of
+packages produced by that branch.
+
+For example, a `foo` repository that is used to build both the current `foo`
+3.x and legacy `foo2` 2.x packages for Debian `unstable` should have branches
+respectively named `debian/latest` and `debian/2/latest`.
+
Managing upstream sources
=========================
