PhoenixDKIM Project Guide

PhoenixDKIM is a security-focused DKIM milter and library descended from
OpenDKIM.  This guide describes release planning, the git branch layout, where
canonical releases live, and the conventions for contributing.


RELEASE PLANNING

PhoenixDKIM uses semantic versioning (x.y.z).

MAJOR RELEASES (x increases): major new features or significant code rewrites.
They may break backward compatibility and are the only releases that may
introduce a new external dependency.  Expect heavy code review and a beta
period.

MINOR RELEASES (y increases): new features or changes that do not warrant a
major release.  Backward compatibility is preserved where practical, and no new
external dependency is introduced.

PATCH RELEASES (z increases): bug and security fixes only -- no new features and
nothing removed.  Backward compatibility must be preserved except where that is
impossible.

Changes under contrib/ are unsupported and may appear in any release.


CANONICAL RELEASES

Releases are tagged on the master branch as "vX.Y.Z" (e.g. "v1.0.0"), as signed
annotated git tags.

The canonical release artifacts are the signed source tarballs published at
https://www.phoenixdkim.org/releases/ :

    phoenixdkim-X.Y.Z.tar.gz        the release tarball
    phoenixdkim-X.Y.Z.tar.gz.asc    its detached OpenPGP signature

GitHub's auto-generated tag archives are NOT canonical: they are not guaranteed
byte-stable and are not signed.  Always prefer the website tarballs, and verify
them:

    gpg --verify phoenixdkim-X.Y.Z.tar.gz.asc phoenixdkim-X.Y.Z.tar.gz

Tarballs and release tags are signed with the PhoenixDKIM release key
(releases@proteamail.com, fingerprint
9FF4 1A44 270A 1D88 226E  50F3 E75C 78A2 8F60 F730).


GIT BRANCH LAYOUT

o master -- pure upstream source.  No distribution packaging lives here, so a
  "git archive" of a release tag is a clean upstream tarball.  Development is
  merged here and releases are tagged from here.

o feature/* and fix/* -- development branches for features and bug fixes
  respectively, merged back to master once reviewed and tested.

o Distribution packaging lives on its own per-target branch, each of which is
  master plus a packaging directory and is kept current with "git merge master"
  (master never touches the packaging directory, so this never conflicts):

      debian/latest  -- packaging for the Debian archive (targets unstable)
      debian/trixie  -- packaging for the local apt repository (targets trixie)

  Fedora/RPM packaging is planned and, if accepted, will follow the same model
  on its own branch; the spec groundwork is in contrib/phoenixdkim.spec.


CONTRIBUTING

1) Match the surrounding coding style (braces, tabs, comments).  The code should
   read as the work of one coherent team.

2) Nothing should introduce compile-time warnings without a documented reason.

3) Any change to libphoenixdkim must leave every unit test passing.  When you
   change library behaviour, add a unit test covering it -- copy an existing
   t-test*.c and adapt it.

4) Build- and run-test a change somewhere before it lands.

5) Document user-visible changes in RELEASE_NOTES (and, for the Debian package,
   debian/changelog).  Trivial fixes need not be documented.

6) Write commit messages that explain WHY the change was made; the diff already
   shows what changed.

7) Bugs and feature requests are tracked on GitHub:
   https://github.com/edmundlod/PhoenixDKIM/issues
   Debian packaging is tracked in the Debian bug tracker (ITP: #1140100).
