On 11/11/14 22:26, Raphael Hertzog wrote:
> 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.
>
What about an extra prefix, e.g. dist/debian/* ?
This would be useful for those cases where the upstream official
repository is willing to keep Debian and Ubuntu branches.
> 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.
I'm in favor of tools working with real upstream tags but would not
expect every upstream to follow one of these three patterns.
Repositories migrated or mirrored from SVN sometimes have tags name
`foo-1.x' or whatever if the SVN tag name was `foo-1.x' so these
arbitrary patterns should be supported somehow.
Typical scenario: somebody mirroring an SVN repository with sync2git
onto Github then forking that repository and creating a Debian branch in
the fork.
>
> 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.
>
--
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/5463afe3.5060...@pocock.pro
