Skip to content

Developer Notes

Jump to bottom Edit New page
Daniel Markstedt edited this page Aug 30, 2024 · 28 revisions

How to Contribute

Netatalk source code is hosted in a shared git repository.

This section describes the general workflow and lifecycle of code contributions in the Netatalk Project, and how to get new code accepted into release branches. It is applicable to Netatalk Team members and external contributors alike. Please read this thoroughly and familiarize yourself with the process before submitting code to the project.

Git Installation

If you haven't used git before, you should probably familiarize yourself with the Git tutorial.

The examples in the following sections are based off of the tools and syntax used by git v1.5.3 or later. Either apt-get, yum, or make install the tools. See Git documentation for more details on this part.

Branching model

  • The main branch is where development of new features is taking place.
  • Branches named branch-netatalk-x-y are for stable releases.
  • Make your code changes in a feature branch, and submit a Pull Request against the target branch.
  • Before submitting PRs against stable branches, please make sure an issue report has been filed first.
  • When patching stable branches, prioritize submitting PRs for those stable branches. The patches can be cherry-picked to main by a maintainer later.
  • The issue report must be referenced in the commit message.
  • We allow rebase merges only; no branch merges.

Review process

We require formal review of all patches with more than trivial code changes.

The author of patch should add a signed-off tag and the reviewer adds a reviewed-by tag. Very formal, but it encourages better coding and documentation.

This means every commit in main should have been reviewed by two team members (if the author is a team member, only one review by another team member needed).

This is inspired by the process used in the Samba project.

Commit messages

Commit messages should have a short, descriptive first summary line that begins with the affected component, and ends with the GitHub issue ticket # e.g.

afpd: new options "force user" and "force group", GitHub #1234

This is helpful when browsing a git log in oneline mode.

Then the commit message should explain what the change is about, the more, the better.

At the end the author adds their signed-off tag.

Basic Netatalk Git

The mother git repository is located at https://github.com/Netatalk/netatalk.git

If you are a Netatalk team member, you create and push work branches directly in the mother repository.

If you are an non-member code contributor (thank you for volunteering!) then work from your own fork of the Netatalk repository. Please follow the GitHub workflow to create your fork, and then clone that fork in the steps below.

Step Zero is to set your name and email address for commits:

$ git config --global user.email [email protected]
$ git config --global user.name "Your Real Name"

Next, clone the repository:

$ git clone https://github.com/Netatalk/netatalk.git 
Initialized empty Git repository in /home/frank/test/.git/
remote: Counting objects: 31503, done.
remote: Compressing objects: 100% (11427/11427), done.
remote: Total 31503 (delta 24830), reused 25450 (delta 19869)
Receiving objects: 100% (31503/31503), 6.52 MiB | 2.38 MiB/s, done.
Resolving deltas: 100% (24830/24830), done.
$ cd netatalk

List local and remote branches:

$ git branch
  * main

$ git branch -r
origin/branch-netatalk-2-0
origin/branch-netatalk-2-1
origin/branch-netatalk-2-2
origin/branch-netatalk-3-0
origin/branch-netatalk-3-1
origin/main

Creating your own working branch from main:

$ git checkout main
$ git checkout -b my_branch
Branch my_branch set up to track remote branch refs/remotes/origin/develop.
Switched to a new branch "my_branch"

Do your own local work:

$ mkdir git-test
$ echo "hello" > git-test/README

View status of changes

$ git status
# On branch my_branch
# Untracked files:
#   (use "git add `<file>`..." to include in what will be committed)
# 
#       git-test/
nothing added to commit but untracked files present (use "git add" to track)

Add our new file to the local branch index:

$ git add git-test
$ git status
# On branch my_branch
# Changes to be committed:
#   (use "git reset HEAD `<file>`..." to unstage)
#
#       new file:   git-test/README
#

Commit changes

$ git commit -m "Example file for HOWTO"
Created commit ad9a1eb: Example file for HOWTO
 1 files changed, 1 insertions(+), 0 deletions(-)
 create mode 100644 git-test/README

Do some more work and commit local changes....

Now fetch the remote branch history:

$ git fetch

To present your patchset properly to other developers, please rebase your patches against the branch you are developing against:

$ git rebase origin/main

Obviously, replace "origin/main" by whatever branch you are developing against. If you have created a mess in your local patch queue, "git rebase -i" might help you out.

Pull Requests

All new code must go through the GitHub Pull Request workflow, which involves at least one project member doing code review and signing off on it, before merging to the target branch.

The description of the workflow can be read in GitHub documentation and will not be repeated here.

The title of the PR should be descriptive and fit on one line. It should not contain the GitHub ticket number. When it is a PR against a stable branch, prepend a tag with the major and minor Netatalk version. For PRs against the main development branch, do not prepend any tags.

A good example:

[3.2] meson: Allow choosing shared or static libraries to build

In the PR summary, make sure you add a description of the purpose of the PR, with a breakdown of the major changes that it is making.

The PR reviewers will be automatically assigned based on the CODEOWNERS settings, so sit back and relax while a project member follows up!

Build system

In the stable netatalk release 3.2.0 (and 2.4.0) we introduced the Meson build system, initially in addition to the traditional GNU autotools build system, but eventually as a full replacement.

Meson is faster at building the netatalk source code by an order of magnitude. Additionally, it allows us in the development team to work more effectively to fix bugs and add functionality. And finally, it removes the need to "bootstrap" the build system which introduces thousands of lines of boilerplate macros.

See the INSTALL file in the netatalk code tree for more details on how to use the Meson build system.

Formatting

We use muon fmt to format all the meson.build files as it applies the meson syntax recommendations to all files. Muon is an independent implementation of Meson that comes with a powerful formatter.

Install muon and save the following script as 'muonfmt' in your local bin directory (chmod +x it too):

#!/bin/bash

find . -type f -name "meson.build" -exec muon fmt -i {} \;

Then all you need to do is:

cd netatalk
muonfmt

Note: In Debian, the muon package and binary are called muon-meson.

Links to Developer Resources

Add a custom footer

Resources

OS Specific Guides

Technical Docs

Development

Clone this wiki locally