[Pkg-zsh-devel] [RFC] Git workflow, take #2

[Frank Terbeck]

Hey * (again),

I've been throwing my initial proposal away entirely.

I have also been considering Axel's comments closely. What follows is my
new take on the subject. It's basically two branches, quilt and some
merging (no rebasing anymore).

I'm pretty confident, that this will fit out needs, but I'm obviously
open for suggestions. :-)

I'm also pretty sure that this would work to keep `zsh' and `zsh-beta'
in the same repository, if that's what we (and Clint) would want (that
would just require another branch, that would do the same as the
`debian' branch for the `zsh' package).

There's some ASCII art included, so read this using a monospaced
font. Also, this is not exhaustive yet. If we're deciding that the basic
concept is sound, I'm willing to put this into way more detailed
descriptions.

Here we go:

* Branches

  This is a quick overview of the branches that are being used for
  debian's zsh package maintenance. This part does not go into much
  detail on how the workflow works. For details about that, see the
  `Workflow' part below.

** upstream

   The upstream sources from <git://zsh.git.sf.net/gitroot/zsh/zsh>.

** debian

   The debian changes for the debian `zsh' package.

   This should initially be based on a clean commit tag from
   `upstream'. When a new upstream release happens, we can merge all
   code changes from the `upstream' branch upto that commit (tag).

** others

   These branches are rather optional and not required for basic
   maintenance for of the `zsh' package.

*** master

    That's the old repository's main branch. We could keep this for
    historical reasons. Or not. I don't have an opinion.

*** debian-beta

    This could basically do *exactly* the same thing as `debian' does,
    but just merge more often. Obviously, that could then be used to
    keep the packaging information for `zsh-beta' if Clint wants to do
    that.

* Workflow

  This is a diagram, that outlines the proposed workflow. Basically,
  the `debian' branch walks alongside the `upstream' branch and
  upstream changes get merged into `debian' at defined points (for the
  non-beta zsh package, that should be upstream commit tags).


        * debian/4.3.11-4
        |
        |   * debian/4.3.11-5
        |   |
        |   |       * debian/4.3.12-1
        |   |       |
        |   |       |   * debian/4.3.12-2
        |   |       |   |
        |   |       |   |           * debian/4.3.13-1
        |   |       |   |           |
        |   |       |   |           | * debian/4.3.13-2
        |   |       |   |           | |
        |   |       |   |           | |   * debian/4.3.13-3
        |   |       |   |           | |   |
        |   |       |   |           | |   |
      a-b-c-d---e-f-g-h-i-------j-k-l-m-n-o   `debian'
     /         /               /
  A-B-C-D-E-F-G-H-I-J-K-L-M-N-O-P-Q           `upstream'
    |         |               |
    |         |               |
    |         |               * zsh-4.3.13
    |         * zsh-4.3.12
    |
    * zsh-4.3.11

** Initial setup

   The current debian version (which is based on the old workflow) is
   4.3.11-3. An initial version on the new workflow would therefore be
   4.3.11-4. It should be based on the upstream tag 4.3.11, and the
   following changes need to be made:

   - Add the debian/ directory
   - Add a quilt patch for the `fuser' completion fix, that was
     included in 4.3.11-3 (this is the only non-debian-dir patch that
     is in this revision).
   - A quilt patch that adds a ./configure script needs to be added.
   - The issue regarding the installation of `Etc/FAQ' needs to be
     addressed.
   - Three new quilt patches for #613162, #611175 and zsh-workers
     28588 should be created.
   - Update debian/changelog

   That should be everthing that would be needed to get debian version
   4.3.11-4 out of the door.


** Working on the package

   Every change to the source (non-debian-dir) should be done by
   adding quilt patches. Permanent patches (patches that would be kept
   in 4.3.12-1) should be named specially ("deb_*" comes to mind).

   When a change justifies the release of a new package version, the
   debian/changelog file should be updated (possibly by using git-dch)
   and the resulting commit should be tagged debian/<zsh-version>-n+1.


** Transitioning to a new upstream version

   When upstream releases a new version, we should follow these steps:

   - Remove all non "deb_*" quilt patches (because the non-permanent
     patches should be included in the upstream version already).
   - Merge `upstream' into `debian'.
   - Update the ./configure script patch in order to catch
     configure.ac changes upstream may have done.
   - update debian/changelog, "New upstream release".
   - Tag debian/<new-zsh-version>-1.

** Generating packages

   I have been evaluating whether `gitpkg' could fit our workflow. And
   I'm fairly sure it does.

   The tool is fairly flexible, but its basic usage is quite simple,
   which is something I liked most about it.

   Say, you'd like to build a package 4.3.12-5, you'd to this:

   % gitpkg debian/4.3.12-5 zsh-4.3.12

   And then you'd end up with the resulting package directory being
   set up in ../deb-packages/zsh/zsh-4.3.12/ with .orig.tar and
   .debian.tar being available in ../deb-package/zsh/.

   As far as I can see, that would fit our needs perfectly.