r321 - in /web: deps/dep14.mdwn index.mdwn

Tue Nov 11 21:05:40 UTC 2014

Author: hertzog
Date: Tue Nov 11 21:05:39 2014
New Revision: 321

URL: http://svn.debian.org/wsvn/dep/?sc=1&rev=321
Log:
Add first draft of DEP-14

Added:
    web/deps/dep14.mdwn
Modified:
    web/index.mdwn

Added: web/deps/dep14.mdwn
URL: http://svn.debian.org/wsvn/dep/web/deps/dep14.mdwn?rev=321&op=file
==============================================================================

--- web/deps/dep14.mdwn	(added)
+++ web/deps/dep14.mdwn	Tue Nov 11 21:05:39 2014
@@ -0,0 +1,209 @@
+[[!meta title="DEP-14: Recommended layout for Git packaging repositories"]]
+
+    Title: Recommended layout for Git packaging repositories
+    DEP: 14
+    State: DRAFT
+    Date: 2014-11-04
+    Drivers: Raphael Hertzog <hertzog at 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 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.
+
+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.
+
+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.
+
+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.
+
+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.

Modified: web/index.mdwn
URL: http://svn.debian.org/wsvn/dep/web/index.mdwn?rev=321&op=diff
==============================================================================
--- web/index.mdwn	(original)
+++ web/index.mdwn	Tue Nov 11 21:05:39 2014
@@ -42,7 +42,7 @@
 **CANDIDATE**  | [*DEP 11: AppStream and Component Metadata for Debian*](http://wiki.debian.org/AppStreamDebianProposal)
 **DRAFT**      | [*DEP 12: Per-package machine-readable metadata about Upstream*](deps/dep12)
 **DRAFT**      | [*DEP 13: Debian specific homepage field*](deps/dep13)
-**RESERVED**   | *DEP 14: Recommended layout for Git packaging repositories*
+**DRAFT**      | [*DEP 14: Recommended layout for Git packaging repositories*](deps/dep14)
 """]]
 
 Additional information


