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

ferm 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.

ferm should really be team maintained. At the moment, it isn't. Packaging is,
however, prepared to be handled by a team. 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 ferm, including bug reports and
upload/migration status. If you want to reach all team members and otherwise
interested parties, write to ferm@packages.debian.org.

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 normaliity, only the person who did the last upload
should merge to any debian/* branch. 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 appropriage 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
  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
  simupstream/latest: needed to synthesize upstream history

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

The repository has had some work to provider a better relation between upstrema
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

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/MaxKellermann/ferm.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/*'

The package history also warrants some comments.

* Upstream started working on the package in svn. The svn repository was
  eventually converted to git. It looks like development branches and also
  some releases got lost in the process
* some older release tags were set in the salsa repository and are missing
  in the upstream repo
* upstream started developing in a subdirectory ferm/ and eventually,
  between v1.1 und v1.2 moved the sources to the root of the repo.
* Bevause of that move, the connection between Debian and upstream history
  was only started with v1.2. Older histories are not connected but still
  as fully visible as they exist.
* If the Debian package was developed under version control in the beginning,
  that history was not preserved until today. This repository contains all
  commits that were available in 2026/05, but still the Debian side of the
  history contains mainly of imported Debian patches.
* Debian's orig.tar files differ from the trees pointed to by upstream's
  release tags. To close the gap, the simupstream branch was created
  * branched off master's release tag v1.2
  * 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 simupstream/HEAD and upstream/* was empty, a 
    simupstream/<release> tag was set
  * and then the next release tag from master merged.
  * start over with checking out the differences from upstream/<number>
  * This was repeated until v2.3.
* Starting with 2.4, there were no diffs between Debian's upstream/* tags
  and upstream's v* tags any more, so simupstream was no longer necessary.
  Either upstream began building their release tarballs from git without 
  postproessing, or Debian started importing from the git release tags.
* 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 simupstream/<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.
* The packages that got uploaded as ferm_2.1-3, ferm_2.1-4, ferm_2.1-5, and
  ferm_2.5-1 were not properly committed to the debian/ history in git
  and were thus branched off retroactively into dead-end branches
* upstream didn't properly tag their 1.2.2 through 1.2.5, 1.3 and
  1.3.1 through 1.3.4 releases. Since Debian's history is only Import and 
  Merge commits in the relevent time window anyway, I didn't bother
  identifying all those commits and let both histories exist without a visible
  connection between 1.2.1 and 2.0.2

