fennel for Debian
-----------------

bootstrap/
~~~~~~~~~~

This top-level directory contains fennel.lua version 0.4.3, the last
non-self-hosting version of the fennel compiler, used strictly for
bootstrapping purposes for building current versions of the compiler.

Importing new upstream releases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

0. Set up the needed tools

If it's the first time doing Debian work on this machine, we'll want
to first install these packages:

  sudo apt install debhelper git-buildpackage pristine-tar cowbuilder pbuilder

We'll be using pbuilder to isolate the build so we can be sure it
works on every machine. The image it uses is initialized using cowbuilder:

  sudo cowbuilder --create

1. Clone this repository

It's easiest to clone Debian packaging git repositories using 'gbp'
from the git-buildpackage package we installed earlier.  We could
of course do so using plain git as well, but we would need to create
the pristine-tar local branch from its respective origin branch
as well (see 'Repository layout' below).

To clone the repository using gbp:

  gbp clone --add-upstream-vcs git@salsa.debian.org:bandali/fennel
  cd fennel

The '--add-upstream-vcs' option requires git-buildpackage 0.9.29 or
later, available in Debian Bookworm (12) and later.  On Debian 11 or
earlier, we need to use these commands instead:

  gbp clone git@salsa.debian.org:bandali/fennel
  cd fennel
  git remote add upstreamvcs https://git.sr.ht/~technomancy/fennel

1.1. Repository layout

If we now run 'git status' in the repository, we can see that the
default branch is 'debian/latest', which is the primary branch for
Debian packaging work - it contains the debian/ directory.

There is also a special 'pristine-tar' branch that efficiently stores
information needed to reproduce byte-for-byte identical orig tarballs
from this repository.

In normal operating scenarios, we would only directly work on the
'debian/*' branches (like debian/latest) and wouldn't manually touch
the pristine-tar branch at all.

Note: As the name debian/latest suggests, this branch should contain
the latest work on the fennel Debian package, typically uploaded to
Debian unstable.  If there is reason to upload to Debian experimental
instead, if the changes are meant to be short-lived on experimental
and will be soon uploaded to unstable as well, they can still go in
the debian/latest branch.  Otherwise, if the changes are likely to be
longer-lived, it's advisable to create a 'debian/experimental' branch
off of debian/latest and do the experimental work there.  This allows
us to work in parallel on other changes for unstable.  Then, when the
experimental changes are ready to be incorporated into unstable, we
would merge the debian/experimental branch back into debian/latest,
and remove the debian/experimental branch afterwards.  See DEP-14 for
more details on this, and for other use-cases for debian/* branches:
https://dep-team.pages.debian.net/deps/dep14/

2. Import the new upstream release

First let's ensure we are on the debian/latest branch and we don't
have any uncommitted changes and are in sync with the current state
of the package repository on Debian Salsa:

  gbp pull

Then fetch all the remotes, especially important for fetching the new
upstream tags that we will soon be merging:

  git fetch --all

Because the upstream has a non-dfsg-compliant file in it, we first
need to merge the upstream release tag into the "upstream/latest+dfsg"
branch. For example, to import a new upstream release 1.5.1, we run:

  git checkout upstream/latest+dfsg
  git merge 1.5.1
  git tag 1.5.1+dfsg
  git checkout debian/latest
  git merge upstream/latest+dfsg

3. Test build the new changes

Before pushing our work, it's a good idea to ensure the package still
builds successfully:

  gbp buildpackage --git-pbuilder

Check for lintian warnings. The "missing-dep-for-interpreter" warning
can be ignored since it is due to a bug in lintian, not a problem in the
package.

4. Push the new changes

If we have commit access to the main copy of this repository on
Debian Salsa, we can simply run 'gbp push' to push our work there.
If not, we will want to fork the repository on Salsa to our personal
account (if not done so previously already), add a git remote pointing
to our fork, and push our work there.  If our Salsa username is 'chey'
this would be something along the lines of:

  git remote add chey git@salsa.debian.org:chey/fennel
  git fetch chey
  gbp push chey

Then notify one of the maintainers of the package to pull in our work
into the main repository.

Note: We keep the debian/changelog series for the new version as
'UNRELEASED' until it is actually being uploaded.

 -- Amin Bandali <bandali@debian.org>, Mon,  5 Feb 2024 14:43:58 -0500
