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

The majority of the tests are also running in the GitHub CI workflow.

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, xsltproc, and python3 on your dev machine; see doc/requirements.txt for required Python libraries)

meson setup build -Dwith-appletalk=true -Dwith-manual=www -Dwith-manual-l10n=ja -Dwith-manual-install-path=/path/to/netatalk-homepage/public/4.0/htmldocs -Dwith-tests=true -Dwith-testsuite=true
meson compile -C build
meson install -C build

Commit the refreshed compile.xml files in doc/

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

The latest manual html files should have been copied to the local netatalk-homepage repository, so commit the changes over there too

Read more about how to work with Documentation

Run the distribution script, and fix any errors

cd build
meson dist
cd ..

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
In the netatalk-homepage repository, author the news story and other version bumps, commit and push.
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:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality, deprecate unused functionality, or introduce changes that require modification to configuration in existing deployment
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

Install Docker Engine in your development environment.
Create and enable a cross-compilation builder.

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

Generate an auth token with your Docker Hub account (read/write/delete privileges).
Log in with your Docker Hub user, and pass the auth token when prompted.

docker login -u yourusername

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

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

Download the latest netatalk release tarball (should be non-bootstrapped)
Rename the tarball to match the debuild naming scheme, typically something like “netatalk_3.2.0.orig.tar.xz”
In the same dir as the tarball, clone the Debian Source from Salsa (see above)
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.

If you don’t have a remote called “upstream”, create it first

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

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

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

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.

Check out the upstream/old branch (or equivalent)
Fetch references from the upstream remote
Do a merge commit with the upstream release tag
Resolve any conflicts (typically due to the Debian source removing certain files.)
Tag upstream/x.y.z (make sure you follow the naming convention)
Check out the `debian/old branch (or equivalent)
Do a merge commit with upstream/x.y.z
Resolve any conflicts
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

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

This is a mirror of the Netatalk GitHub Wiki. Please visit the original page if you want to correct an error or contribute new contents.

Last updated 2024-12-09

netatalk.io

search netatalk.io

Table of contents