Developing the 7kaa Package In Git
==================================

Development Dependencies
------------------------

This package is developed using git-buildpackage, pristine-tar, and
licensecheck.  This author also prefers to use sbuild with `~/.sbuildrc`
containing `$lintian_opts = ['--display-info', '--pedantic'];`, but any clean
environment that runs lintian is fine for test building.

Cherry Picking Upstream Patches
-------------------------------

Crash and purely local UI fixes may be cherry picked from the upstream
branch only if they don't drastically change gameplay or affect multiplayer
compatibility.  Like many online multiplayer games, this game requires all
players to use the same functionally equivalent version.  Do not cherry pick any
fixes without ensuring that multiplayer compatibility will be unaffected.  When
in doubt, ask upstream or don't cherry pick, because simple crash fixes are
uncommon in 7kaa and multiplayer effects can be hard to notice.  Overall, patch
as little as possible.

    https://www.7kfans.com/forums/viewtopic.php?f=20&t=1302#p9804
    https://dont-ship.it/

Git Commit Message Style Guide
------------------------------

The following guidelines for commit messages maintain consistency with previous
`debian/changelog` entries and the use of gbp-dch, lintian, etc.:

  * Limit all lines to 76 columns (72 columns is recommended, e.g. by Git
    itself).  When converted to an indented list in `debian/changelog`,
    the resulting lines will be up to 80 columns wide.  lintian will warn
    (debian-changelog-line-too-long) if any lines are wider than 80 columns.
  * End all sentences, including on line 1, with a full stop (`.`), for
    consistent gbp-dch output.  If additional details follow, consider ending
    line 1 with a colon (`:`) instead.
  * Skip line 2 and begin additional details, if any, on line 3.  Git joins all
    lines until the first empty line, resulting in one long summary line.
  * Begin list items with `+ ` (convention of longtime maintainer Bertrand
    Marc) or `- ` on the first line and `  ` on subsequent lines.
  * When committing changes to fix a previous commit within the same release in
    progress, append a blank line and `Gbp-Dch: Ignore` to the commit message.
    `debian/changelog` should describe only changes relative to the previous
    release.

GitLab Merge Requests
---------------------

If merging using the Web interface, check "Edit commit message".  Append a blank
line and `Gbp-Dch: Ignore` to the merge commit message.  "Merge branch 'foo'
into 'master'" changes don't belong in `debian/changelog`.

Typographical Conventions
-------------------------

In the below command blocks, `$ ` is the first-line shell prompt.  Commands
that are too long to fit on one line are split with a `\` escape, a newline, and
the continuation-line shell prompt `> `.  When typing these commands, skip the
`$ ` and `> ` prompts, and you can enter them on a single line without the '\'.

Workflow: New Upstream Version
------------------------------

Clone the Git repository:

    $ gbp clone --all git@salsa.debian.org:games-team/7kaa.git
    $ cd 7kaa/
    $ git remote add upstream https://git.code.sf.net/p/skfans/7kaa

Create the patch queue branch on the old version (unnecessary if
`use_system_libuuid.patch` is the only patch, since it only touches files
removed by uscan):

    $ gbp pq import
    $ git checkout master

Run licensecheck on the old version:

    $ licensecheck --recursive --copyright --deb-machine --merge-licenses \
    > $(git ls-files -- . ':!:*.COL' ':!:*.ICN' ':!:*.BMP' ':!:*.RES' \
    > ':!:*.BIN' ':!:*.SCN' ':!:*.SCP' ':!:*.WAV' ':!:*.SPR' ':!:*.TUT' \
    > ':!:*.png' ':!:debian/') 1>../7kaa.licensecheck.old

Import new upstream version:

    $ gbp import-orig --upstream-vcs-tag="$(git tag --list 'v*' \
    > --sort=-version:refname | head -n 1)" \
    > --import-msg='New upstream version %(version)s.' --uscan --no-interactive
    $ git commit --amend --message="New upstream version $(git tag --list \
    > 'upstream/*' --sort=-version:refname | sed '1{ s|^upstream/||; q; }')."

If this version has notable changes and/or fixes bugs, amend the commit message
to note them (remember to skip line 2):

    $ git commit --amend

Refresh patches (unnecessary if `use_system_libuuid.patch` is the only patch):

    $ gbp pq rebase
    $ # Edit files and commit changes here.  Use `Gbp-Pq: Name ...`.
    $ gbp pq export --commit
    $ GIT_EDITOR='sed -i "1s/\$/./"' git commit --amend  # Assumes GNU sed.
    $ gbp pq drop

Fix the order of patches and edit `<REASON>`:

    $ git commit --amend

Run licensecheck on the new version, compare the differences, and update
`debian/copyright`:

    $ licensecheck --recursive --copyright --deb-machine --merge-licenses \
    > $(git ls-files -- . ':!:*.COL' ':!:*.ICN' ':!:*.BMP' ':!:*.RES' \
    > ':!:*.BIN' ':!:*.SCN' ':!:*.SCP' ':!:*.WAV' ':!:*.SPR' ':!:*.TUT' \
    > ':!:*.png' ':!:debian/') 1>../7kaa.licensecheck.new
    $ diff -u ../7kaa.licensecheck.old ../7kaa.licensecheck.new \
    > 1>../7kaa.licensecheck.diff
    $ ${EDITOR:-vim -O} debian/copyright ../7kaa.licensecheck.diff

Tip: if using Vim, you can put the cursor over a file name and open the file in
a new tab with `CTRL-W gf` (`:help CTRL-W_gf` for details) to view and yank
copyright and license notices.

Stage and commit the updates:

    $ git commit --message='debian/copyright: Update.' -- debian/copyright

Update `Standards-Version:` and `debhelper-compat` if necessary and make any
other changes.

Update `debian/changelog` and release:

    $ gbp dch --full --release --new-version="$(git tag --list 'upstream/*' \
    > --sort=-version:refname | sed '1{ s|^upstream/||; s|$|-1|; q; }')" \
    > --git-log='master --not upstream' --git-author --multimaint-merge \
    > --commit-msg='Update changelog for %(version)s release.' --commit

In the spawned editor, manually remove any remaining merge commits (e.g. "See
merge request" commits from GitLab merge requests) **except for a "New upstream
version" commit**.

Build:

    $ gbp buildpackage --git-pristine-tar --git-builder=sbuild

Push to GitLab:

    $ git push --tags origin master:master upstream:upstream \
    > pristine-tar:pristine-tar

If additional changes are necessary but an "Update changelog for ... release."
commit has already been made, you can update the changelog again by first
reverting to "UNRELEASED":

    $ sed -i '1s/ [^ ;][^ ;]*;/ UNRELEASED;/' debian/changelog
    $ gbp dch --full --release --git-log='master --not upstream' \
    > --git-author --multimaint-merge \
    > --commit-msg='Update changelog for %(version)s release.' --commit

After the package is uploaded to the Debian package archive, tag the release:

    $ git tag "debian/$(dpkg-parsechangelog --show-field Version)"
    $ git push --tags origin

 -- P. J. McDermott  Fri, 22 Dec 2023 12:02:40 -0500
