r322 - /web/deps/dep14.mdwn

[hertzog at users.alioth.debian.org]

Author: hertzog
Date: Tue Nov 11 21:12:45 2014
New Revision: 322

URL: http://svn.debian.org/wsvn/dep/?sc=1&rev=322
Log:
Fix headings and reorder slightly a section

Modified:
    web/deps/dep14.mdwn

Modified: web/deps/dep14.mdwn
URL: http://svn.debian.org/wsvn/dep/web/deps/dep14.mdwn?rev=322&op=diff
==============================================================================
--- web/deps/dep14.mdwn	(original)
+++ web/deps/dep14.mdwn	Tue Nov 11 21:12:45 2014
@@ -13,7 +13,7 @@
 
 
 Introduction
-------------
+============
 
 This is a proposal to harmonize the layout of Git repositories
 used to maintain Debian packages. The goals are multiple:
@@ -28,7 +28,7 @@
    (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.
@@ -36,10 +36,10 @@
 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
@@ -56,7 +56,7 @@
 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.
@@ -64,7 +64,7 @@
 (`~`) 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
@@ -92,6 +92,9 @@
 `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
 ------------------------------------------
@@ -116,10 +119,6 @@
 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
 -----------------------------------------
 
@@ -137,8 +136,15 @@
 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
@@ -157,7 +163,7 @@
 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
@@ -170,14 +176,14 @@
 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
@@ -190,7 +196,7 @@
 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
@@ -204,6 +210,6 @@
 branches.
 
 Changes
--------
+=======
 
 * 2014-11-05: Initial draft by Raphaël Hertzog.