Release Process

Process for preparing and publishing Netatalk releases. The intended audience for this document is Netatalk project maintainers.

Run the spectest test suite

The spectest test suite ensures that there are no breakages in AFP specification conformance.

• Build netatalk with the testsuite Add-on enabled.

meson setup build -Dwith-testsuite=true
meson compile -C build

• Follow the instructions in test/testsuite/README to configure and run the tests

Fix any failing tests, either the test code itself (if it is malfunctioning) or the non-compliant netatalk code.

Making a stable release

• Update CONTRIBUTORS if any new code contributors have emerged

• Update NEWS and commit the changes.

• Bump version number by editing meson.build and update the "version" line near the top. Commit the changes.

Note For 3.x and 2.x branches, also update the version string in VERSION.

• Build netatalk with manual and tests (requires docbook-xsl and xsltproc on your dev machine)

meson setup build -Dwith-appletalk=true -Dwith-manual=www -Dwith-manual-l10n=ja -Dwith-tests=true -Dwith-testsuite=true
meson compile -C build

Note For 3.x and 2.x branches, commit the regenerated troff man pages in the man/ dir at this point

• Copy the generated manual pages to the netatalk-homepage repository and commit the changes

cp build/doc/manual/*.html /path/to/netatalk-homepage/public/4.0/htmldocs
cp build/doc/ja/manual/*.html /path/to/netatalk-homepage/public/4.0/htmldocs/ja

Read more about how to work with Documentation

• Run the distribution script, and fix any errors

cd build
meson dist

• Once the distribution builds cleanly, tag the release.
• Requires a PGP public key to be registered with GitHub in order to sign the tag.

git tag -s netatalk-3-2-0
git push origin netatalk-3-2-0

• Create the Webmin Module release tarball

meson setup build -Dwith-webmin=true -Dwith-install-hooks=false --reconfigure
meson compile -C build
meson install -C build --tags webmin

• Reset version to the "dev" version of the next planned release, e.g. 3.1.19dev

• In the GitHub web interface, draft a new release. Choose the tag that you just pushed to the remote. Name the release and generate the release notes. Write a summary of the release, and touch up the changelog if needed.

• Upload the xz compressed tarball and checksum file that were created in ./build/meson-dist plus the Webmin Module tarball in ./build/contrib/webmin_module

• Commit updates to the html manual to the netatalk-homepage repository, generate html release notes, and author other release updates to the homepage.

• Synchronize branches and tags with the netatalk GitLab mirror

Versioning Scheme

This project uses a custom variant of Semantic Versioning.

Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes
2. MINOR version when you add functionality, deprecate unused functionality, or introduce changes that require modification to configuration in existing deployment
3. PATCH version when you make backward compatible bug fixes, or add minor functionality

Historically, this project has used alpha and beta suffices for early major and minor releases, but this is not a practice at the time of writing.

Docker

Build and publish netatalk Docker images.

Environment Preparation

1. Install Docker Engine in your development environment.

2. Create and enable a cross-compilation builder.

docker buildx create --name mybuilder --bootstrap --use

3. Generate an auth token with your Docker Hub account (read/write/delete privileges).

4. Log in with your Docker Hub user, and pass the auth token when prompted.

docker login -u yourusername

5. Cross compile and tag Docker images with docker buildx and push to the Docker Hub container registry. We currently cross compile for 32bit/64bit x86, and 32bit/64bit ARM.

docker buildx build --push --platform=linux/386,linux/amd64,linux/arm/v6,linux/arm64 . -t netatalk/netatalk:latest -t netatalk/netatalk:4 -t netatalk/netatalk:4.0 -t netatalk/netatalk:4.0.0

7. That's it! Confirm that the new image is published in the right repository: https://hub.docker.com/u/netatalk

Debian deb packaging

This section is written from the perspective of a Debian package maintainer, but can be leveraged to build your own deb package for personal use or unofficial distribution. Please note that this is just one of many ways to package software for Debian. When in doubt, refer to official Debian documentation rather than this section.

The modified Debian source code is managed in git in Debian Salsa. You can also get it with the apt source netatalk command (requires your release to have the package.)

Environment prep

First off, install all Debian packaging tools and configure the environment.

Then, read through the rest of the chapters in the linked manual before proceeding.

Leverage chroot environments to have a clean system for building and testing. Note that debuild will create deb packages for the specific OS version it is running on, so chroot enables you to control this.

If needed, set up cross-compilation to generate debs for architectures other than your actual machine.

Prepare the Debian Source

1. Download the latest netatalk release tarball (should be non-bootstrapped)
2. Rename the tarball to match the debuild naming scheme, typically something like "netatalk_3.2.0.orig.tar.xz"
3. In the same dir as the tarball, clone the Debian Source from Salsa (see above)
4. Fetch the upstream references (create a new remote for the upstream git repo if needed.)

New netatalk release (automated)

When working off the latest mainline release series (e.g. 3.x) you can use gbp to automate the process.

1. If you don't have a remote called "upstream", create it first

git remote add upstream https://github.com/Netatalk/netatalk.git

2. Fetch the latest references from upstream, git fetch upstream
3. Make sure the following branches have local checkouts: debian/latest upstream/latest pristine-tar
4. Merge the latest release tag

gbp import-orig --upstream-vcs-tag=netatalk-x-y-z --uscan

5. Indicate the latest version number when prompted, e.g. "3.2.0-ds"

A successful run should look something like this:

gbp:info: Launching uscan...
Newest version of netatalk on remote site is 3.2.0, local version is 3.1.18
       (mangled local version is 3.1.18)
 => Newer package available from:
        => https://github.com/Netatalk/netatalk/archive/refs/tags/netatalk-3-2-0.tar.gz
uscan warn: No files matched excluded pattern as the last matching glob: etc/spotlight/sparql_parser.c
uscan warn: No files matched excluded pattern as the last matching glob: etc/spotlight/sparql_parser.h
uscan warn: No files matched excluded pattern as the last matching glob: etc/spotlight/spotlight_rawquery_lexer.c
uscan warn: No files matched excluded pattern as the last matching glob: include/atalk/tdb.h
uscan warn: No files matched excluded pattern as the last matching glob: libatalk/talloc/talloc.c
uscan warn: No files matched excluded pattern as the last matching glob: libatalk/tdb/*
Successfully repacked ../netatalk--3-2-0.tar.gz as ../netatalk_3.2.0.orig.tar.xz, deleting 1 files from itgbp:info: Using uscan downloaded tarball ../netatalk_3.2.0.orig.tar.xz
What is the upstream version? [3.2.0] 
gbp:info: Importing '../netatalk_3.2.0.orig.tar.xz' to branch 'upstream/latest' (filtering out ['*/.git*'])...
gbp:info: Source package is netatalk
gbp:info: Upstream version is 3.2.0
gbp:info: Replacing upstream source on 'debian/latest'
gbp:info: Successfully imported version 3.2.0 of ../netatalk_3.2.0.orig.tar.xz

New netatalk release (manual)

When working off older branches, i.e. 2.x, the following manual process can be used.

1. Check out the upstream/old branch (or equivalent)
2. Fetch references from the upstream remote
3. Do a merge commit with the upstream release tag
4. Resolve any conflicts (typically due to the Debian source removing certain files.)
5. Tag upstream/x.y.z (make sure you follow the naming convention)
6. Check out the `debian/old branch (or equivalent)
7. Do a merge commit with upstream/x.y.z
8. Resolve any conflicts
9. From the root of the salsa source, run pristine-tar commit ../netatalk2_x.y.z.orig.tar.xz upstream/x.y.z to create a pristine tar commit in the "pristine-tar" branch

Local changes to the deb

1. Run ./debian/copyright-check and commit any changes to "./debian/copyright_hints"
2. Manually merge relevant updates from "copyright_hints" to "copyright"
3. Make appropriate updates to any other files under "debian/"
4. Remove any obsoleted patches under "debian/patches"
5. Unfuzz patches that apply with fuzz, or not at all. e.g. dquilt push 202_privacy.patch -f ... edit then dquilt refresh
6. If needed, create new patches with dquilt and put them under "debian/patches"
7. From the root of the Debian source, run dch -v x.y.z~ds-n (with appropriate versioning numbers) to generate the changelog
8. Write the changelog and commit
9. From the root of the Debian source, run debuild
10. If the build passes, check the lintian log
11. If there are any lintian warnings or errors, fix them
12. Test the created deb package in the parent directory by installing it with dpgk
13. Tag the release git tag x.y.z~ds-n
14. Push all branches (upstream/latest debian/latest pristine-tar) and tags (upstream/x.y.z debian/x.y.z~ds-n) to remote
15. You did it!