[Pkg-zsh-devel] pkg-zsh.git workflow, Second Draft

[Axel Beckert]

Hi,

a few comments, the obvious (non-question) ones plus some typos are
already fixed at https://github.com/xtaran/pkg-zsh-doc/commits/master

Frank Terbeck wrote:
> *** Changes
> 
>     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).
> 
>     To keep order for cases in which a vast number of patches are
>     required, any quilt patch needs to be numbered according to the
>     order in which "quilt series" would list them. The format looks
>     like this:
> 
>        - deb_NNNN_<name>.diff
>        - NNNN_<name>.diff
> 
>     Where `N' is a digit from 0 to 9. Counting starts at `0000'.

Here it is important that all deb_NNNN_* patches are applied after the
NNNN_* patches since we don't want to sent patches upstream which are
based on debian-specific patches.

> **** Dealing with quilt's .pc directory
> 
>      When quilt works, it keeps track of what it does in a directory
>      by the name `.pc'. This directory will show up in the output of
>      "git status" etc. It should *never* *ever* by committed to the
>      git repository at any point.
> 
>      We cannot add the directory to `.gitignore' because we would
>      change the zsh source directly instead of via `debian/patches'.
> 
>      To deal with the directory, there is another git-facility, that
>      we can use for fun and profit.
> 
>      % echo .pc/ >> .git/info/exclude

I thought, $HOME/.gitignore would work here, but it doesn't. :-(

Can't we ask upstream to include /.pc in their .gitignore? :-)

> **** Example of adding a fix via a quilt patch
> 
>      Let's say, there is an issue `#12345' which can be fixed by
>      patching `Functions/Misc/colors'. Here is how you could add that
>      patch (assuming clean git working directory):
> 
>      ## First, add all exising patches, so the new one is added on top.
>      % quilt push -a
> 
>      ## Add the new patch (say, the topmost patch is 0002-foo.diff).
>      % quilt new 0003-fix-colors.diff
> 
>      ## Tell quilt which files are going to be changed.
>      % quilt add Functions/Misc/colors
> 
>      ## Import the fix (manually by editor or by patching).
>      % vi Functions/Misc/colors

Here's a "quilt refresh" missing.

>      ## Pop all patches again to clean up the upstream source.
>      % quilt pop -a
> 
>      ## Commit the new patch and the changes `series' file to git.
>      % git add debian/patches/0003-fix-colors.diff
>      % git add debian/patches/series
>      % git commit -a -m'Fixing foo in colors function (Closes: #12345)'
> 
>      That's all.
[...]
> *** Fix outstanding bug
> 
>     If *any* outstanding bugs are known, they should be fixed before
>     releasing a new package. Obviously, if any of the known bugs are
>     very hard to fix and the issue is not serious in nature, releasing
>     the package with the issue may be more important.

Hmm, this is looks irritating to me. I'd like to have the last
sentence be either "releasing the package with the fixed issue may be
more important" or "releasing the package with the unfixed issue may
be more important".

But I also think that this section can be dropped anyway, because 

a) it's obvious

b) cases where you can't fix all outstanding bugs in a release are far
   too often so that we would need more exceptions than cases where this
   rule applies.

I suggest to just remove that paragraph or rephrase it even more
relaxed. (Yeah, I know, it's a "should" in there. It nevertheless
sounds too much like something which nearly never can be achieved.)
What do you think?

>     `gitpkg' is available from:
> 
>     <http://git.debian.org/?p=users/ron/gitpkg.git>
[...]
>     <https://honk.sigxcpu.org/piki/projects/git-buildpackage/>

Since we do Debian packaging here, we should primarily rely on Debian
packages in our infrastructure, so the Debian packages should be
mentioned at all first and before the upstream download/repo URLs.

Frank, would you merge my changes? Do we have a place for the current
official version? Maybe some htmlized version in the
pkg-zsh.alioth.debian.org web?

		Regards, Axel
-- 
 ,''`.  |  Axel Beckert <abe at debian.org>, http://people.debian.org/~abe/
: :' :  |  Debian Developer, ftp.ch.debian.org Admin
`. `'   |  1024D: F067 EA27 26B9 C3FC 1486  202E C09E 1D89 9593 0EDE
  `-    |  4096R: 2517 B724 C5F6 CA99 5329  6E61 2FF9 CD59 6126 16B5