CONTRIBUTING.md

Contributing to libyang

First of all, thanks for thinking about contribution to libyang! Not all of us are C guru, but believe that helping us with docs, tests, helping other users to solve their issues / answer ther questions or even letting us to know via issue tracker that something can be done in a better or just different way is really appreciated.

If you are willing to contribute, you will definitely have to build and install libyang first. To do it, please check dependencies and follow build and install instructions provided in README.

If you have something what you believe should be part of the libyang repository, add it via Github Pull Request mechanism. Remember to explain what you wish to add and why. The best approach is to start with creating an issue and discuss possible approaches there. Pull requests can be then connected with such issues.

Branches

There are 2 main branches in libyang project. The default branch is named master. It is the most stable and tested code which you get by default when cloning the Git repository. The devel branch introduces new features, API changes or even bugfixes in case master and devel differs significantly at that moment and the fix affects the changed code. There are some more branches for work-in-progress features and special coverity branch for submitting code for the analysis in the Coverity tool usign Travis CI build.

When you create pull request, think carefully about the branch where the patch belongs to. In most cases (if not all), it is the devel branch.

Issue Ticketing

All the communication with the developers is done via issue tracker. You can send us an email, but in case you will ask a question we would think that someone else could ask in future, our answer will be just use the issue tracker. Private emails are not visible for others and we don't want to answer the same questions.

So when you are goingto submit a new issue, please:

• check that the issue you are having is not already solved in the devel branch,
• go through the present issues (in case of question, it can be already a closed issue) in the tracker,
• give it as descriptive title as possible,
• separate topics - solving multiple issues in one ticket hides the issues from others,
• provide as much relevant information as possible (versions, logs, input data, etc.).

libyang Coding Style

When you are going to contribute C code, please follow these coding style guidelines.

Basics

• Use space instead of tabs for indentations.
• There is no strict limit for the line length, However, try to keep lines in a reasonable length (120 characters).
• Avoid trailing spaces on lines.
• Put one blank line between function definitions.
• Don't mix declarations and code within a block. Similarly, don't use declarations in iteration statements.

Naming

Use underscores to separate words in an identifier: multi_word_name.

Use lowercase for most names. Use uppercase for macros, macro parameters and members of enumerations.

Do not use names that begin with _. If you need a name for "internal use only", use __ as a suffix instead of a prefix.

Comments

Avoid // comments. Use /* ... */ comments, write block comments with the leading asterisk on each line. You may put the /* and */ on the same line as comment text if you prefer.

/*
 * comment text
 */

Functions

Put the return type, function name, and the braces that surround the function's code on separate lines, all starting in column 0.

static int
foo(int arg)
{
    ...
}

When you need to put the function parameters on multiple lines, start new line at column after the opening parenthesis from the initial line.

static int
my_function(struct my_struct *p1, struct another_struct *p2,
            int size)
{
    ...
}

In the absence of good reasons for another order, the following parameter order is preferred. One notable exception is that data parameters and their corresponding size parameters should be paired.

1. The primary object being manipulated, if any (equivalent to the "this" pointer in C++).
2. Input-only parameters.
3. Input/output parameters.
4. Output-only parameters.
5. Status parameter.

Functions that destroy an instance of a dynamically-allocated type should accept and ignore a null pointer argument. Code that calls such a function (including the C standard library function free()) should omit a null-pointer check. We find that this usually makes code easier to read.

Function Prototypes

Put the return type and function name on the same line in a function prototype:

static const struct int foo(int arg);

Statements

• Indent each level of code with 4 spaces.
• Put single space between if, while, for, etc. statements and the expression that follow them. On the other hand, function calls has no space between the function name and opening parenthesis.
• Opening code block brace is kept at the same line with the if, while, for or switch statements.

if (a) {
    x = exp(a);
} else {
    return 1;
}

• Start switch's cases at the same column as the switch.

switch (conn->state) {
case 0:
    return "data found";
case 1:
    return "data not found";
default:
    return "unknown error";
}

• Do not put gratuitous parentheses around the expression in a return statement, that is, write return 0; and not return(0);

Types

Use typedefs sparingly. Code is clearer if the actual type is visible at the point of declaration. Do not, in general, declare a typedef for a struct, union, or enum. Do not declare a typedef for a pointer type, because this can be very confusing to the reader.

Use the int<N>_t and uint<N>_t types from <stdint.h> for exact-width integer types. Use the PRId<N>, PRIu<N>, and PRIx<N> macros from <inttypes.h> for formatting them with printf() and related functions.

Pointer declarators bind to the variable name, not the type name. Write int *x, not int* x and definitely not int * x.

Expresions

Put one space on each side of infix binary and ternary operators:

* / % + - << >> < <= > >= == != & ^ | && || ?: = += -= *= /= %= &= ^= |= <<= >>=

Do not put any white space around postfix, prefix, or grouping operators with one exception - sizeof, see the note below.

() [] -> . ! ~ ++ -- + - * &

The "sizeof" operator is unique among C operators in that it accepts two very different kinds of operands: an expression or a type. In general, prefer to specify an expression

int *x = calloc(1, sizeof *x);

When the operand of sizeof is an expression, there is no need to parenthesize that operand, and please don't. There is an exception to this rule when you need to work with partially compatible structures:

struct a_s {
   uint8_t type;
}

struct b_s {
   uint8_t type;
   char *str;
}

struct c_s {
   uint8_t type;
   uint8_t *u8;
}
...
struct a_s *a;

switch (type) {
case 1:
    a = (struct a_s *)calloc(1, sizeof(struct b_s));
    break;
case 2:
    a = (struct a_s *)calloc(1, sizeof(struct c_s));
    break;
    ...