Debian Vim source package handling
----------------------------------
The Debian package of Vim is maintained in Mercurial.  URLs are as follows:

  Anonymous: http://hg.debian.org/hg/pkg-vim/vim
  Web browsing: http://hg.debian.org/hg/pkg-vim/vim
  Authenticated, for developers with commit access:
    ssh://hg.debian.org/hg/pkg-vim/vim

Maintaining Patches
-------------------
This package uses quilt to manage all modifications to the upstream source.
Changes are stored in the source package as diffs in debian/patches and
applied automatically by dpkg-source when the source package is extracted.

To configure quilt to use debian/patches instead of patches, you want either
to export QUILT_PATCHES=debian/patches in your environment or use this
snippet in your ~/.quiltrc:

    where=./
    while [ "$(readlink -e $where)" != "/" ]; do
        if [ -e ${where}debian/rules -a -d ${where}debian/patches ]; then
            QUILT_PATCHES=debian/patches
            break
        else
            where=${where}../
        fi
    done
    unset where

After unpacking the source package, all patches will be applied, and you can
use quilt normally.

If you check out the source code from hg, then all patches will be applied,
but you will need to inform quilt of this manually.  Do this by running:

    debian/rules quilt-setup

To add a new set of changes, apply all relevant existing patches, and then run:

    quilt new <patch>

where <patch> is a descriptive name for the patch, used as the filename in
debian/patches.

Patches which aren't necessarily Debian-specific shall be named
upstream/$feature.patch whereas patches which are purely Debian-specific shall
be named debian/$feature.patch.

All upstream patches shall be earlier in the patch series than Debian-specific
patches so the former aren't cluttered with changes that aren't relevant to
upstream.

For patches to runtime files, prefer the naming scheme of
$filetype-{syntax,ftplugin,indent}-$feature.patch for the filename.

Then, for every file that will be modified by this patch, run:

    quilt add <file>

before editing those files or use

    quilt edit <file>

to begin editing the file.  You must tell quilt what files will be part of the
patch before making changes or quilt will not work properly.  Both “quilt add”
and “quilt edit” will do this for you.

After editing the files, run:

    quilt refresh

to save the results as a patch.

Alternately, if you already have an external patch and you just want to add
it to the build system, run “quilt push -a” and then:

    quilt import -P <patch> /path/to/patch
    quilt push -a

(add -p 0 to quilt import if needed). <patch> as above is the filename to
use in debian/patches.  The last “quilt push -a” will apply the patch to make
sure it works properly.

To remove an existing patch from the list of patches that will be applied,
run:

    quilt delete <patch>

You may need to run “quilt pop -a” to unapply patches first before running
this command.

You should only commit changes to hg with all patches applied, i.e. after
“quilt push -a”.

Updating upstream source
------------------------
It is important to update vim-runtime.preinst.in to remove old diversions
during upgrades to a new major version release.

Preparing uploads
-----------------
If you're building a package with new upstream patches, a new
orig.tar.gz needs to be built.  This can be built once debian/changelog has
been updated with the appropriate version.  Running “debian/rules update-orig”
will export a properly named tarball to the parent directory using the hash in
the upstream version.

For example, a version of 2:7.2.411+hg~24100651daa9-1 in debian/changelog will
cause commit 24100651daa9 (which corresponds to the commit of patch 7.2.411 in
upstream's repository) to be exported as
vim_7.2.411+hg~24100651daa9.orig.tar.gz.
