netatalk.io

How to Contribute to Netatalk

This project uses Git for code revision control and collaboration.

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.

Using Git

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

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.
• When applicable, the issue report key must be referenced in the commit message.
• We allow rebase merges only; no branch merges.

Review process

We require formal peer review of all patches before merging to the main or stable branches.

The code review can be carried out by any Netatalk Developer.

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 context the better.

Basic Netatalk Git

The mother git repository is located at https://github.com/Netatalk/netatalk.git with a mirror at https://gitlab.com/netatalk-team/netatalk.git.

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

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.

.gitignore

The policy in this project is to define .gitignore patterns only for files and directories that are generated by the netatalk build system. So for instance, the macOS .DS_Store metadata file, or IDE settings files, should not be filtered out in the netatalk .gitignore file.

If a developer wants to filter out environment specific files, we recommend creating a global .gitignore file for your particular setup.

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!

Alternative patch submission

If you are unable to use the GitHub Pull Request workflow for some reason, you can also submit patches by email to the netatalk-devel mailing list.

Please follow the guidelines in the Developer FAQ for instructions on how to create and submit patches by email.

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. As of version 4.0.0, autotools macros were completely removed, and Meson is now the only build system option.

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

Copyright and license

The Netatalk project as a whole is distributed under the GNU GPL v2. Code covered by other, compatible, FLOSS licenses are also included in the package.

It is strongly recommended that new code contributed to this project is also licensed under the GNU GPL v2 license. This is an example copyright header that you can put in the top of new source files, formatted as a C code comment.

/*
 * Copyright (C) Firstname Lastname 20XX
 * All Rights Reserved.  See COPYING.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 */

For other languages, use the appropriate code comment syntax.

Coding Standards

The baseline C language standard revision for the netatalk codebase is C11.

Note that since the netatalk code was originally written in the early 90s, there are still parts of the codebase that is archaic. Contributors are welcome and encouraged to modernize the code and use recent C language conveniences compliant with C11.

The use of memory safe standard library BSD-isms such as strnlen(), strlcpy(), and strlcat() is also encouraged. In fact, include/atalkd/compat.h contains wrappers for these three functions for standard C libraries that don’t support them natively.

C static analysis

Certain coding conventions and best practices are enforced through static analysis provided by SonarQube.

This project uses a custom Quality Profile, so you can refer to this for the current list of active static analysis rules.

New code must not introduce any Security, Reliability, or Maintainability bugs. Changed code must not contain any Security or Reliability bugs, but Maintainability bugs are tolerated.

Note that project members will get immediate feedback by the CI workflow, while external contributors’ code will only get scanned after being merged for technical reasons.

C code style

This project has adopted a C coding style guide applied across the entire codebase. The intended outcome is to make the code more readable, and to make collaboration and maintenance easier. With automated enforcement of the style guide, the manual overhead of fiddling with layout is eliminated.

Automatic formatting

The style guide is automatically enforced with astyle v3.6.x and an .astylerc options file. Before submitting new code, run astyle --project --recursive '*.h' '*.c' in the root of the netatalk source tree. You can also use the ./contrib/scripts/codefmt.sh convenience script to the same effect.

Rules

• General rules
• Four space indentation
• Max 80 char line lengths
• Variable and function names should be in snake_case
• Lists of symbols, files etc. should be sorted in alphabetic order, unless a constraint dictates otherwise
• One variable declaration and definition per line
• Alphanumeric symbols in optarg should be in alphabetical order, with unary options first and parameter options second

Ex.

getopt(ac, av, "flsA:D:m:r:")

• Headers
• Cluster headers in this order: First system libraries, second 3rd party libraries, third libatalk headers, fourth local headers

• Within each cluster: Sort header include directives in alphabetical order, unless a particular sequence is required

• Braces

• Starting braces are broken from function definitions, but attached for all other block types
• When on the same line, one space padding between condition and starting brace
• Always use braces on single-line blocks

Ex.

int return_zero(int i)
{
    if (i == 0) {
        return 0;
    }
}

• Code comments
• C style comments, not C++ style
• Comments should come on the line before the code it describes
  • Exception: Trailing Doxygen comments (see below)
• Single line: /* Your comment goes here */
• Multi line comments use a * prefix

Ex.

/*
 * Your comment goes here
 */

• Code documentation
• We use a Doxygen based documentation system for code documentation, with:
  • QDoc style /*! ... */ markers
  • Use /*!< ... */ to for trailing comments
  • JavaDoc style @ prefixed commanded tags
• Most comment blocks should include @brief, @param and @returns
• Indicate input/output status for @param with [in],[out], and [in,out] tags
• Surround code blocks with @code ... @endcode for proper formatting
• Use CommonMark markdown for rich formatting, for instance for numbered and bulleted lists

Ex.

/*!
 * @brief Inititialize rootinfo key (which has CNID 0 as key)
 *
 * @note This also "stamps" the database, which means storing st.st_ctime
 * of the "cnid2.db" file in the rootinfo data at the DEV offset
 *
 * @param[in,out] dbd       database handle
 * @param[in] version       database version number
 *
 * @returns -1 on error, 0 on success
 */
static int dbif_init_rootinfo(DBD *dbd, int version)
{
    ...
}

• Padding and alignment
• Pointer and reference operators (*, &, or ^) should be aligned to the variable name
• One space padding after comma
• One space padding after paren headers (‘if’, ‘for’, etc.)
• One space padding before and after operators (‘+’, ‘-‘, etc.)
• No padding for unary operators (‘i++’)

• No padding inside parentheses or brackets (‘if (1 == 0)’)

• Empty lines and trailing spaces

• No trailing spaces
• Max one empty line in sequence
• Empty line padding before and after unrelated blocks, labels, etc.

Meson code style

We use Muon’s opinionated formatter - muon fmt - to format all the meson.build files as it applies the meson syntax recommendations to all files.

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

You can also use the ./contrib/scripts/codefmt.sh convenience script to the same effect.

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

Perl code style

Perl code distributed with netatalk should follow the common style guide, enforced by perltidy and the .perltidyrc config file.

For example, it should use four space indentation with a max 120 char line length.

Brace, square bracket, and parentheses tightness should be max, meaning no inner space padding. The exception is block braces, which should have a one space padding. Opening braces should always be trailing at the right of the condition or method definition, with a cuddled else statement.

Shell script code style

First off, we expect all shell scripts distributed with netatalk to be POSIX compliant and run in the sh interpreter.

As with the other code styles, we expect four space indentation, including for switch statements. We also like to see a one space padding between all operators.

The coding style is enforced through an .editorconfig file in the repo root, together with the shfmt beautifier.