README.source for the aide Debian package
=========================================

aide is a rather normal 3.0 (quilt) package that is maintained on salsa.  It
has a decades long history. The Repository on salsa (see debian/control) can be
cloned and worked with like it is common in Debian. However, there are some
specialities that you do not NEED to be aware of but it might help.


The Team
--------
aide is maintained by a small team. One team member also is Upstream. If you
want to participate, first thing would be to subscribe to the package's mail
messages through tracker.debian.org. Since the maintainer address is set to the
tracker, that way you'll get all messages relevant to aide, including bug
reports and upload/migration status. If you want to reach all team members and
otherwise interested parties, write to aide@packages.debian.org.


Branches and commit suggestions
-------------------------------
Nobody should directly commit to debian/latest (with the exception of preparing
an upload). All work should be done through personal branches. It is best
practise to file a merge request after finishing work on a personal branch and
let somebody else approve and/or merge to debian/latest for a
four-eyes-workflow. In normality, only the person who did the last upload
should merge to any debian/* branch without their agreement. If that person
does not react in a few days (or it is very urgent), any other person in
Uploaders may step in.


Branch names
------------
debian/latest: the latest Debian packaging. This branch should always be
   in a state to build without failure. Can be uploaded to experimental
   and/or unstable
debian/releasename: security, stable updates. branched off debian/latest
   when needed from the appropriate debian/<number> tag.
debian/unstable: only exists when unstable work was neeed while
   debian/latest holds an experimental branch. branched off
   debian/latest from the latest debian/<number> tag that got
   uploaded to unstable
upstream/latest: upstream source
upstream/ancient: ancient upstream source, synthesizing upstream development
   up to 0.13.1
master: upstream source from the upstream vcs
user/name: user-specific branch to work in. Feel free to use that namespace
   even if you're not formally on the team. Clean up after yourself. Branches
   stale more than a year are subject to deletion
upstream/simulated: needed to synthesize and merge upstream history

debian/* branches are protected, no force push here.


How to clone
------------
The repository has had some work to provide a better relation between upstream
and Debian work. Method 4 outlined in
https://wiki.debian.org/HavingUpstreamGitHistoryInDebianGit was used for the
first time to bring this interweaving also to the historiy commits.

While you should be able to use this repository normally if you don't care, the
full beauty of the history will become visble for you when you
* add the upstream vcs as a second remote:
  * git remote add upstreamvcs https://github.com/aide/aide.git
  * git fetch upstreamvcs
  * and
* pull the replacement refs from the salsa repository which do not come
  automatically with git clone or git fetch:
  * git fetch origin 'refs/replace/*:refs/replace/*'


How to update upstream
----------------------
In theory, updating to a new upstream release/snapshot should be done by means
of gbp import-orig --uscan. That does not work at the moment (see #1138228).
For the time being, update as follows:
- fetch upstreamvcs
- Find the upstream tag you want to update to
- Manually find and download the corresponding
- git switch upstream/latest (or a upstream maintenance/devel branch
    if your upstream tag is not on the mainline history)
- git merge <upstream-tag>
- gbp import-orig --debian-branch=debian/x <upstream-tarball>
  make sure to set the debian-branch if you don't want to import to
  debian/latest (which is the default).


Package history
---------------
The package history also warrants some comments.

* Ancient history shows some collaboration between Upstream and Debian.
  Upstream was already working in some kind of version control, but sadly,
  their commit history didn't survive.
* Debian packaging was first done in cvs and eventually migrated to svn.
* Debian history goes farther back than upstream's, so the very early upstream
  history was synthesized from the very early Debian history. Hence, you see
  many commits once on the Upstream side and once on the Debian side. To avoid
  loop which might have interfered with git replace later, those commits were
  cherry-picked, creating different commit IDs.
* To be able to preserve the upstream commit IDs, the early Upstream history
  was not synthesized on the upstream/latest branch proper, but on the
  upstream/ancient branch. Both branches were connected to each other at the
  release of aide 0.13.1 by doing git replace.
* Debian's packaging history went from cvs to svn to eventually git, and for a
  while the repository was in debian/ only form. The regular method of
  maintaining aide in git also started with 0.13.1-1.
* Debian's orig.tar files differ from the trees pointed to by upstream's
  release tags due to upstream's release process of not committing the
  autoconf artifacts to git but including them in the release tarball.
  To close the gap, the upsteam/simulated branch was created
  * started with cherry-picking the ancient history up to aide.0.10.release.
  * differences to the upstream/<number> tag were pulled from the
    respective upstream/* tags. It was important not to merge from
    upstream/*. The differing files were pulled via git checkout and
    then explicitly committed.
  * once the diff between upstream/simulated/HEAD and upstream/* was empty, a 
    upstream/simulateed/<release> tag was set
  * and then the next release tag from master was merged.
  * start over with checking out the differences from upstream/<number>
  * This was repeated until v0.19.2 was reached.
* Then the connection between upstream's release tags and Debian's upstream/*
  tags was built by calling "git replace a b" with, for all upstream versions
  x, a being the commit pointed to by the upstream/<x> tag and b being the
  commit pointed to by either the "v<x>" or the upstream/simulated/<x>" tag.
  Care was taken that the diff between the tag being replaced and the tag
  replacing was empty.
* In the result you can see in git log --oneline --graph --all a nice
  mixture of Debian and upstream commits, and are thus able to put
  upstream and Debian development in relation to each other.
* Debian did not package every upstream release.
* There is significant confusion in debian/latest when the packages alternated
  between the 0.x.y maintenance branch and git snapshots taken from the
  development branch. This was in error on the Debian side not being aware of
  upstream's development/maintenance branch and resulted in huge merge diffs.
  upstream/latest still does reflect the actual Debian release history.
