Hello, following the initial discussion we had in August (https://lists.debian.org/debian-devel/2014/08/thrd2.html#00499), I have written a first draft of the Debian Enhancement Proposal that I suggested. It's now online at http://dep.debian.net/deps/dep14 and also attached below so that you can easily reply and comment.
I have left one question where I have had conflicting feedback and I'm not sure what's best. Thus I will welcome a larger set of opinions on this specific question (search for "QUESTION" in the text). Are there things that are missing? Here's the draft: Title: Recommended layout for Git packaging repositories DEP: 14 State: DRAFT Date: 2014-11-04 Drivers: Raphael Hertzog <hert...@debian.org> URL: http://dep.debian.net/deps/dep14 Source: http://anonscm.debian.org/viewvc/dep/web/deps/dep14.mdwn Abstract: Recommended naming conventions in Git repositories used to maintain Debian packages Introduction ============ This is a proposal to harmonize the layout of Git repositories used to maintain Debian packages. The goals are multiple: * making it easier for Debian and its derivatives to build upon their respective Git repositories (with the possibility to share a common one in some cases) * make it easier to switch between various git packaging helper tools. Even if all the tools don't implement the same worflow, they could at least use the same naming conventions for the same things (Debian/upstream release tags, default packaging branch, etc.). Scope ===== This proposal defines naming conventions for various Git branches and Git tags that can be useful when doing Debian packaging work. The hope is that maintainers of git packaging helper tools will adopt those naming conventions (in the default configuration of their tools). Generic principles ================== Vendor namespaces ----------------- Each "vendor" uses its own namespace for its packaging related Git branches and tags: `debian/*` for Debian, `ubuntu/*` for Ubuntu, and so on. Helper tools should usually rely on the output of `dpkg-vendor --query vendor` to find out the name of the current vendor. The retrieved string must be converted to lower case. This allows users to override the current vendor by setting `DEB_VENDOR` in their environment (provided that the vendor information does exist in `/etc/dpkg/origins/`). If `dpkg-vendor` is not available, then they should assume "debian" is the current vendor. Helper tools can also offer a command-line option to override the current vendor if they desire. Version mangling ---------------- When a Git tag needs to refer to a specific version of a Debian package, the Debian version needs to be mangled to cope with Git's restrictions. The colon (`:`) needs to be replaced with a percent (`%`), and the tilde (`~`) needs to be replaced with an underscore (`_`). Packaging branches and tags =========================== Packaging branches should be named according to the codename of the target distribution. In the case of Debian, that means for example `debian/sid`, `debian/jessie`, `debian/experimental`, `debian/wheezy`, `debian/wheezy-backports`, etc. We specifically avoid "suite" names because those tend to evolve over time ("stable" becomes "oldstable" and so on). The Git repository listed in debian/control's `Vcs-Git` field should usually have its HEAD point to the branch corresponding to the distribution where new upstream versions are usually sent. For Debian, it will usually be `debian/sid` (or sometimes `debian/experimental`). QUESTION: some people have argued to use debian/master as the latest packaging targets sometimes sid and sometimes experimental. Should we standardize on this? Or should we explicitly allow this as an alternative? The helper tools that do create those repositories should use a command like `git symbolic-ref HEAD refs/heads/debian/sid` to update HEAD to point to the desired branch. When releasing a Debian package, the packager should create and push a signed tag named `<vendor>/<version>`. For example, a Debian maintainer releasing a package with version 2:1.2~rc1-1 would create a tag named `debian/2%1.2_rc1-1` whereas an Ubuntu packager 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. Managing upstream sources ========================= Importing upstream release tarballs in Git ------------------------------------------ If the Git workflow in use imports the upstream sources from released tarballs, this should be done under the "upstream" namespace. By default, the latest upstream version should be imported in the `upstream/latest` branch and when packages for multiple upstream versions are maintained concurrently, one should create as many upstream branches as required. Their name should be based on the major upstream version tracked: for example when upstream maintains a stable 1.2 branch and releases 1.2.x minor releases in that branch, those releases should be imported in a `upstream/1.2.x` branch (the ".x" suffix makes it clear that we are referring to a branch and not to the tag corresponding the upsteam 1.2 release). If the upstream developers use codenames to refer to their releases, the upstream branches can be named according to those codenames. Helper tools should detect when the upstream version imported is lower than the latest version available in `upstream/latest` and should offer either to create a new branch (based on the highest version available in the history that is still smaller than the imported version) or to pick another pre-existing upstream branch. Importing upstream releases from Git tags ----------------------------------------- When the packaging branches are directly based on the upstream Git branches, upstream usually also provide proper Git tags that can be reused for official releases. If helper tools have to identify the upstream commit corresponding to a given upstream release, they should be able to find it out by looking up the following Git tags: `upstream/<version>`, `<version>` and `v<version>`. The `upstream/<version>` tag would be created by the package maintainer 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. About pristine-tar ------------------ If the package maintainers use the pristine-tar tool to efficiently store a byte-for-byte copy of the upstream tarballs, this should be done in the `pristine-tar` branch. Native packages =============== The above conventions mainly cater to the case of non-native packages, that is when the upstream developers and the package maintainers are not the same set of persons. When upstream is Debian (or one of its derivative), the upstream vendor should not use the usual `<vendor>/` prefix (but all others vendors should do so). The main development branch can be named `master` instead of the codename of the target distribution (although you are free to still use the codename if you wish so). When the package is shipped as a native source package, the concept of "upstream sources" is irrelevant and the associated `upstream/*` branches are irrelevant too. Note that even if the upstream vendor ships the package as a native package, the downstream vendors can still can opt to package it in a non-native way. Patch queue tags ================ A patch queue branch is a (temporary) branch used to define the set of upstream changes that the package will contain, its content is generally used to later update `debian/patches` in the resulting source package. Helper tools that want to store a copy of the "patch queues branches" for released versions of the packages should create a tag named `<vendor>/patches/<version>`. That tag should usually point to the upstream branch with vendor patches applied on top of it. Other recommendations ===================== This sections ventures a bit outside of the topic of naming conventions with some further suggestions for package maintainers and developers of helper tools. What to store in the Git repository ----------------------------------- It is recommended that the packaging branches contain both the upstream sources and the Debian packaging. Users who have cloned the repository should be able to run `dpkg-buildpackage -b -us -uc` without doing anything else (assuming they have the required build dependencies). It is also important so that contributors are able to use the tool of their choice to update the debian/patches quilt series: multiple helper tools need the upstream sources in Git to manage this patch series as a Git branch. Managing debian/changelog ------------------------- This DEP makes no specific recommendation on how to manage the Debian changelog. Some maintainers like to use tools like `gbp dch` to generate the changelog based on Git commit notices, others edit the file manually and use tools like `debcommit` to reuse the changelog entry in the Git commit. Helper tools should however configure the Git repository so that merges of the `debian/changelog` file are handled by `dpkg-mergechangelogs` as this will make it much easier to merge between different packaging branches. Changes ======= * 2014-11-05: Initial draft by Raphaël Hertzog. -- Raphaël Hertzog ◈ Debian Developer Support Debian LTS: http://www.freexian.com/services/debian-lts.html Learn to master Debian: http://debian-handbook.info/get/ -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: https://lists.debian.org/20141111212624.ga19...@home.ouaza.com