Developer Notes

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 for stable releases
currently stable release branch branch-netatalk-3-1
commits go to main (after a review, more on that below)
commits can only go into a release branch if an issue report exists
the issue report must be referenced in the commit message
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”, #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.

In the PR summary, make sure you add a description of the purpose of the PR, and a link back to the GitHub issue ticket.

Links to Developer Resources

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-04-23

netatalk.io

search netatalk.io

Table of contents