[Python-modules-commits] [python-modules] 04/09: Fill out the basics of the git policy requirements.

[Barry Warsaw]

This is an automated email from the git hooks/post-receive script.

barry pushed a commit to branch git-policy
in repository python-modules.

commit bd514873f1a5bb7426b4adac2c76e1431a28bb72
Author: Barry Warsaw <barry at python.org>
Date:   Tue Oct 20 16:49:30 2015 -0400

    Fill out the basics of the git policy requirements.
---
 policy.rst | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 87 insertions(+), 13 deletions(-)

diff --git a/policy.rst b/policy.rst
index aed57c0..123792c 100644
--- a/policy.rst
+++ b/policy.rst
@@ -20,9 +20,9 @@
 
 .. contents::
 
-----------------
+
 Joining the team
-----------------
+================
 
 The team is open to any Python-related package maintainer. To be added to
 the team, please send your request to debian-python at lists.debian.org.  Include
@@ -48,9 +48,9 @@ discussion list or on #debian-python IRC channel (OFTC network).
 All team members should of course follow the main discussion list:
 debian-python at lists.debian.org
 
---------------
+
 Maintainership
---------------
+==============
 
 A package maintained within the team should have the name of the team either
 in the ``Maintainer`` field or in the ``Uploaders`` field.
@@ -73,28 +73,102 @@ python-modules-team at lists.alioth.debian.org whereas members who are only
 interested in some packages should use the Package Tracking System to
 follow the packages.
 
---------------
+
 Git Procedures
---------------
+==============
 
 As of October 9, 2015, the DPMT uses git as the version control system for all
-packages, and git-dpm as the patch management regime.  Details of the
-procedures, standards for branches and tags, and common workflows are
-maintained on the `Debian wiki <https://wiki.debian.org/Python/GitPackaging>`_
+packages, and git-dpm as the patch management regime.
+
+Git repositories live on Alioth under the url
+``git+ssh://git.debian.org/git/python-modules/packages/<src-pkg-name>.git``
+To access any source package's repository, use ``gbp clone`` on the above url,
+substituting *src-pkg-name* for the source package name of the package in
+question.
+
+DPMT git repos are **source-full**, meaning they contain both the upstream
+source and the ``debian/`` directory.
+
+DPMT requires upstream tarballs; releases cannot be made from upstream git
+repositories directly.  This is because PyPI contains upstream tarballs, and
+tarballs are what we upload to the Debian archive.
+
+Deviations from this policy are strongly discouraged.  When you must (not want
+to) deviate, you MUST include a ``debian/README.source`` file explaining the
+rationale for the deviation and the details of working with the package's git
+repo.
+
+
+Tools
+-----
+
+``gbp build-package`` is used to build the package, either as a source package
+for use with ``pbuilder``, ``sbuild``, etc. or as a binary package directory.
+Do *not* create ``quilt`` patches directly.  Instead, use ``git-dpm
+checkout-patched`` to enter a patch branch, edit the files, commit them, and
+then use ``git-dpm update-patches`` to switch back to the master branch, with
+the commits turned into patches.  Use the pseudo header ``Patch-Name`` in the
+commit message to control what the patch file will be named, e.g.::
+
+    Patch-Name: fix-the-foo.patch
+
+Use ``git-dpm tag`` to tag the repository when you upload a new release of the
+package.  See below for the required tag format.
+
+
+Branch names
+------------
+
+Currently, we require the following branch names in the git repo:
+
+* master - The Debianized upstream source directory.  This contains both the
+  upstream source and a ``debian/`` packaging directory.
+* pristine-tar - Contains the standard ``pristine-tar`` deltas.
+* upstream - The un-Debianized upstream source.  This is what you get when you
+  unpack the upstream tarball.
+
+In some cases you may need to have additional branches, such as if you have
+deltas for downstream distributions (e.g. Ubuntu) or need to maintain multiple
+versions for security releases in previous versions of Debian.  In those
+cases, follow the `DEP-14 <http://dep.debian.net/deps/dep14/>`_ guidelines,
+and document them in ``debian/README.source``.
+
+
+Tag format
+----------
+
+Use the following ``git-dpm`` tag formats for the three branches named above.
+Put these lines at the *end* of your ``debian/.git-dpm`` file::
+
+    debianTag="debian/%e%v"
+    patchedTag="patches/%e%v"
+    upstreamTag="upstream/%e%u"
+
+All packages which have been automatically converted from the old Subversion
+repository should already have these lines present, but you will need to add
+them for any new packages.
+
+
+More information
+----------------
+
+Additional information for working with DPMT git repositories, creating new
+repositories, common workflows, and helpful hints, can be found on the
+`Debian wiki <https://wiki.debian.org/Python/GitPackaging>`_
 page.
 
------------------
+
 Quality Assurance
------------------
+=================
 
 The goal of the team is to maintain all packages as best as possible.
 Thus every member is encouraged to do general QA work on all the
 packages: fix bugs, test packages, improve them to use the latest python
 packaging tools, etc.
 
--------
+
 License
--------
+=======
 
 Copyright (c) 2005-2015 Debian Python Modules Team. All rights reserved.
 This document is free software; you may redistribute it and/or modify

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/tools/python-modules.git