Skip to content

Developer Notes

Jump to bottom Edit New page
Daniel Markstedt edited this page Jan 12, 2024 · 30 revisions

Code Contribution Process

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 on 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 external code contributor (thank you for contributing!) 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 Your.Email@domain.com
$ 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.

Updating Documentation

The Netatalk documentation consists of two parts: the man pages and the manual on the website. Both are managed in docbook XML format under the doc/ directory in the source tree.

When making code changes that warrant an update to the documentation, such as adding, changing or deprecating functionality, please make sure the updates to the xml sources for the documentation are included as part of the changeset in your PR.

If the changeset of your PR warrants a bullet point in the changelog, please include an update to NEWS as part of your changeset as well.

Administrative Workflows

Making a release

  • Bump VERSION
$ echo "x.x.x" > VERSION
$ git commit -a -m "Bump version to x.x.x"
  • Update NEWS as necessary:
$ vi NEWS
$ git commit -a -m "Update NEWS"
  • Re-run configure so the VERSION bump gets passed to the build system
$ ./configure

  • Run make distcheck, fix any errors

  • Regenerate manpages from XML sources using docbook-xsl stylesheets

Source a non-namespaced copy of docbook-xsl, f.e. from your OS's package repo (use the package without the -ns suffix) or from SourceForge, then configure with --with-docbook pointing to the absolute path of the docbook-xsl directory.

At the time of writing, the final non-namespaced docbook-xsl release is docbook-xsl-1.79.1 on SourceForge. The packages published on GitHub are namespaced by default. See this upstream bug for more info.

Note: Netatalk 2 has a different workflow for generating and uploading man and html pages.

$ ./configure --with-docbook=/absolute/path/to/docbook-xsl-1.79.1
$ make html
$ git add man
$ git commit -a -m "Generate manpages from XML"
  • Tag, release and roll tarballs
$ git tag TAG
$ git push origin TAG
$ make dist
$ make dist-bzip2
  • Upload updates to online manual:
$ cd doc/manual/
$ USER=netatalk-sourceforge-adminuser make html-upload

  • Reset VERSION to eg 3.0.8dev

  • 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. Touch up the release notes if needed, upload both xz and bz2 tarballs generated by the build system, and publish the release.

  • Update the website

After updating the website resources, push to the SourceForge webserver with:

 scp -r *.php css gfx
[adminuser]@web.sourceforge.net:/home/project-web/netatalk/htdocs/

Technical Information

Creating patches

This describes the traditional method of creating plain text patch files. It can be useful when requesting feedback for your code on the mailing lists, or when contributing patches downstream to distro repositories. These steps are optional if you're submitting a PR on GitHub.

Assuming your patches are the last three commits on your current local git branch, this is the easiest way to create patches from them:

$ git format-patch -3

This will create three patch files in your current directory that you can then send to the netatalk-devel mailing list.

Note that if you have a number of patches against a specific branch and don't feel like counting them, the following works as well (e.g. against the main branch):

$ git format-patch origin/main

This will create one patch file for every patch that is in your local branch but not in origin/main.

If you have more patches which belong together it's sometimes useful to export them into one file:

$ git format-patch --stdout origin/main > develop-featureX-01.patches.txt

Debugging process crashes

We need a stack-backtrace (SBT) from a corefile with debugging symbols.

  • Compile Netatalk with debugging symbols and without optimizations, e.g. for gcc
CFLAGS="-g -O0" ./configure ... && make && make install
  • Enable global corefile generation (Linux, Solaris)
  • Enable corefile generation for Netatalk by adding
ulimit -c unlimited

... at the beginning of the Netatalk start script and restart Netatalk.

  • Reproduce issue
  • Get SBT (example for a crash of afpd and gdb):
$ gdb path/to/afpd path/to/corefile
(gdb) bt full
...
(gdb) exit

Integration tests

In order to run the integration tests located in test/ run make with the check target:

$ make -j
$ make check

FAQ

Q. How do I revert a commit?

A. The "git reset" command allows you to reset the HEAD of the branch to any given point in history. To go back one commit, run

$ git reset HEAD^

This will keep your local changes and you can make any additional changes before re-committing the new work. Also see the "git commit --amend" command and the "git reset" man page for other examples.

If the branch has already been pushed to remote, you can force-push the amended branch. Please be careful with force pushing, since it can be a destructive action.

$ git push origin my-work-branch --force

Q. How can I maintain a feature branch against the upstream Netatalk branches?

A. You clone the Netatalk repository as per the instructions above. Then you make a new feature branch:

$ git checkout -b feature_foo main

Now you do your development in your feature branch. Any time the main branch gets too different to the code in your feature branch you should rebase your feature branch. The rebase rewinds your feature branch to the point there it was branched. Then it updates your feature branch to the HEAD of the main branch and re-applies your changes.

$ git rebase main
First, rewinding head to replay your work on top of it...
HEAD is now at 357f003... Add WERR_SERVICE_ALREADY_RUNNING.
...
Wrote tree 02299ef7c1cfa093248bfd9c6e3812805718845e
Committed: e20a8c521d7860d9b7bd724ed5ea19c7306530ab

Rebase works best when you use it for local branches that are never pushed to a public repository, see Why won't "git push" work after I rebased a branch?.

Links to Developer Resources

Add a custom footer

Resources

OS Specific Guides

Technical Docs

Development

Clone this wiki locally