From cd07912073c951b4bbb871ed2653af1be2cfc714 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 11:55:11 +0200 Subject: Adding upstream version 2.1.30. Signed-off-by: Daniel Baumann --- CONTRIBUTING.md | 228 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 CONTRIBUTING.md (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b150904 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,228 @@ +# 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](https://github.com/CESNET/libyang/issues) 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](README.md). + +If you have something what you believe should be part of the libyang repository, +add it via [Github Pull Request mechanism](https://help.github.com/articles/about-pull-requests/). +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](https://scan.coverity.com/projects/5259) usign +[Travis CI build](https://travis-ci.org/CESNET/libyang/branches). + +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](https://github.com/CESNET/libyang/issues). +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. + +```c +/* + * 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. + +```c +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. + +```c +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: + +```c +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. + +```c +if (a) { + x = exp(a); +} else { + return 1; +} +``` + +- Start switch's cases at the same column as the switch. + +```c +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_t` and `uint_t` types from `` for exact-width +integer types. Use the `PRId`, `PRIu`, and `PRIx` macros from +`` 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: + +```c +* / % + - << >> < <= > >= == != & ^ | && || ?: = += -= *= /= %= &= ^= |= <<= >>= +``` + +Do not put any white space around postfix, prefix, or grouping operators with +one exception - `sizeof`, see the note below. + +```c +() [] -> . ! ~ ++ -- + - * & +``` + +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 +```c +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: + +```c +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; + ... +``` -- cgit v1.2.3