Skip to content

Commit a80971f

Browse files
rkrejcirkrejci
committed
doc CHANGE add project documentation files
1 parent 4ab6156 commit a80971f

File tree

3 files changed

+501
-0
lines changed

3 files changed

+501
-0
lines changed

‎CONTRIBUTING.md

+228
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# Contributing to libyang
2+
3+
First of all, thanks for thinking about contribution to libyang! Not all of us
4+
are C guru, but believe that helping us with docs, tests, helping other users to
5+
solve their issues / answer ther questions or even letting us to know via
6+
[issue tracker](https://github.com/CESNET/libyang/issues) that something
7+
can be done in a better or just different way is really appreciated.
8+
9+
If you are willing to contribute, you will definitely have to build and install
10+
libyang first. To do it, please check dependencies and follow build and install
11+
instructions provided in [README](README.md).
12+
13+
If you have something what you believe should be part of the libyang repository,
14+
add it via [Github Pull Request mechanism](https://help.github.com/articles/about-pull-requests/).
15+
Remember to explain what you wish to add and why. The best approach is to start
16+
with creating an issue and discuss possible approaches there. Pull requests can be
17+
then connected with such issues.
18+
19+
## Branches
20+
21+
There are 2 main branches in libyang project. The default branch is named `master`. It is the
22+
most stable and tested code which you get by default when cloning the Git repository. The
23+
`devel` branch introduces new features, API changes or even bugfixes in case `master` and
24+
`devel` differs significantly at that moment and the fix affects the changed code. There are
25+
some more branches for work-in-progress features and special `coverity` branch for submitting
26+
code for the [analysis in the Coverity tool](https://scan.coverity.com/projects/5259) usign
27+
[Travis CI build](https://travis-ci.org/CESNET/libyang/branches).
28+
29+
When you create pull request, think carefully about the branch where the patch belongs to.
30+
In most cases (if not all), it is the `devel` branch.
31+
32+
## Issue Ticketing
33+
34+
All the communication with the developers is done via [issue tracker](https://github.com/CESNET/libyang/issues).
35+
You can send us an email, but in case you will ask a question we would think that someone else
36+
could ask in future, our answer will be just **use the issue tracker**. Private emails are not visible
37+
for others and we don't want to answer the same questions.
38+
39+
So when you are goingto submit a new issue, **please:**
40+
* check that the issue you are having is not already solved in the devel branch,
41+
* go through the present issues (in case of question, it can be already a closed issue) in the tracker,
42+
* give it as descriptive title as possible,
43+
* separate topics - solving multiple issues in one ticket hides the issues from others,
44+
* provide as much relevant information as possible (versions, logs, input data, etc.).
45+
46+
## libyang Coding Style
47+
48+
When you are going to contribute C code, please follow these coding style guidelines.
49+
50+
### Basics
51+
52+
- Use space instead of tabs for indentations.
53+
- There is no strict limit for the line length, However, try to keep lines in a
54+
reasonable length (120 characters).
55+
- Avoid trailing spaces on lines.
56+
- Put one blank line between function definitions.
57+
- Don't mix declarations and code within a block. Similarly, don't use
58+
declarations in iteration statements.
59+
60+
### Naming
61+
62+
Use underscores to separate words in an identifier: `multi_word_name`.
63+
64+
Use lowercase for most names. Use uppercase for macros, macro parameters and
65+
members of enumerations.
66+
67+
Do not use names that begin with `_`. If you need a name for "internal use
68+
only", use `__` as a suffix instead of a prefix.
69+
70+
### Comments
71+
72+
Avoid `//` comments. Use `/* ... */` comments, write block comments with the
73+
leading asterisk on each line. You may put the `/*` and `*/` on the same line as
74+
comment text if you prefer.
75+
76+
```c
77+
/*
78+
* comment text
79+
*/
80+
```
81+
82+
### Functions
83+
84+
Put the return type, function name, and the braces that surround the function's
85+
code on separate lines, all starting in column 0.
86+
87+
```c
88+
static int
89+
foo(int arg)
90+
{
91+
...
92+
}
93+
```
94+
95+
When you need to put the function parameters on multiple lines, start new line
96+
at column after the opening parenthesis from the initial line.
97+
98+
```c
99+
static int
100+
my_function(struct my_struct *p1, struct another_struct *p2,
101+
int size)
102+
{
103+
...
104+
}
105+
```
106+
107+
In the absence of good reasons for another order, the following parameter order
108+
is preferred. One notable exception is that data parameters and their
109+
corresponding size parameters should be paired.
110+
111+
1. The primary object being manipulated, if any (equivalent to the "this"
112+
pointer in C++).
113+
2. Input-only parameters.
114+
3. Input/output parameters.
115+
4. Output-only parameters.
116+
5. Status parameter.
117+
118+
Functions that destroy an instance of a dynamically-allocated type should accept
119+
and ignore a null pointer argument. Code that calls such a function (including
120+
the C standard library function `free()`) should omit a null-pointer check. We
121+
find that this usually makes code easier to read.
122+
123+
#### Function Prototypes
124+
125+
Put the return type and function name on the same line in a function prototype:
126+
127+
```c
128+
static const struct int foo(int arg);
129+
```
130+
131+
### Statements
132+
133+
- Indent each level of code with 4 spaces.
134+
- Put single space between `if`, `while`, `for`, etc. statements and the
135+
expression that follow them. On the other hand, function calls has no space
136+
between the function name and opening parenthesis.
137+
- Opening code block brace is kept at the same line with the `if`, `while`,
138+
`for` or `switch` statements.
139+
140+
```c
141+
if (a) {
142+
x = exp(a);
143+
} else {
144+
return 1;
145+
}
146+
```
147+
148+
- Start switch's cases at the same column as the switch.
149+
150+
```c
151+
switch (conn->state) {
152+
case 0:
153+
return "data found";
154+
case 1:
155+
return "data not found";
156+
default:
157+
return "unknown error";
158+
}
159+
```
160+
161+
- Do not put gratuitous parentheses around the expression in a return statement,
162+
that is, write `return 0;` and not `return(0);`
163+
164+
### Types
165+
166+
Use typedefs sparingly. Code is clearer if the actual type is visible at the
167+
point of declaration. Do not, in general, declare a typedef for a struct, union,
168+
or enum. Do not declare a typedef for a pointer type, because this can be very
169+
confusing to the reader.
170+
171+
Use the `int<N>_t` and `uint<N>_t` types from `<stdint.h>` for exact-width
172+
integer types. Use the `PRId<N>`, `PRIu<N>`, and `PRIx<N>` macros from
173+
`<inttypes.h>` for formatting them with `printf()` and related functions.
174+
175+
Pointer declarators bind to the variable name, not the type name. Write
176+
`int *x`, not `int* x` and definitely not `int * x`.
177+
178+
### Expresions
179+
180+
Put one space on each side of infix binary and ternary operators:
181+
182+
```c
183+
* / % + - << >> < <= > >= == != & ^ | && || ?: = += -= *= /= %= &= ^= |= <<= >>=
184+
```
185+
186+
Do not put any white space around postfix, prefix, or grouping operators with
187+
one exception - `sizeof`, see the note below.
188+
189+
```c
190+
() [] -> . ! ~ ++ -- + - * &
191+
```
192+
193+
The "sizeof" operator is unique among C operators in that it accepts two very
194+
different kinds of operands: an expression or a type. In general, prefer to
195+
specify an expression
196+
```c
197+
int *x = calloc(1, sizeof *x);
198+
```
199+
When the operand of sizeof is an expression, there is no need to parenthesize
200+
that operand, and please don't. There is an exception to this rule when you need
201+
to work with partially compatible structures:
202+
203+
```c
204+
struct a_s {
205+
uint8_t type;
206+
}
207+
208+
struct b_s {
209+
uint8_t type;
210+
char *str;
211+
}
212+
213+
struct c_s {
214+
uint8_t type;
215+
uint8_t *u8;
216+
}
217+
...
218+
struct a_s *a;
219+
220+
switch (type) {
221+
case 1:
222+
a = (struct a_s *)calloc(1, sizeof(struct b_s));
223+
break;
224+
case 2:
225+
a = (struct a_s *)calloc(1, sizeof(struct c_s));
226+
break;
227+
...
228+
```

‎LICENSE

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
Copyright (c) 2015-2016, CESNET
2+
All rights reserved.
3+
4+
Redistribution and use in source and binary forms, with or without
5+
modification, are permitted provided that the following conditions are met:
6+
7+
* Redistributions of source code must retain the above copyright notice, this
8+
list of conditions and the following disclaimer.
9+
10+
* Redistributions in binary form must reproduce the above copyright notice,
11+
this list of conditions and the following disclaimer in the documentation
12+
and/or other materials provided with the distribution.
13+
14+
* Neither the name of libyang nor the names of its
15+
contributors may be used to endorse or promote products derived from
16+
this software without specific prior written permission.
17+
18+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
22+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
25+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
26+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28+

0 commit comments

Comments
 (0)