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.
