1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
:doctitle: OpenDataPlane (ODP) CONTRIBUTING
:description: This document is intended to guide a new application developer +
in understanding the contributing requirements for ODP
:imagesdir: ../images
:toc:
:numbered!:
[abstract]
== Abstract
This document is intended to guide a new application developer in understanding
the contributing requirements for ODP
== New Development
ODP code shall be written with the kernel coding style
https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst[Kernel Coding Style]
ODP code shall be documented using the doxygen style described in the
"Documenting the code" section.
Check patch script/checkpatch.pl shall be used before submitting a patch.
== ODP patch expectations as an open source project
While specific to the Linux kernel development, the following reference could
also be considered a general guide for any Open Source development
http://ldn.linuxfoundation.org/book/how-participate-linux-community[Participating in the Community]
and is relevant to ODP. Many of the guidelines in this ODP document are related
to the items in that information.
Pay particular attention to section 5.3 that talks about patch preparation.
The key thing to remember is to break up your changes into logical sections.
Otherwise you run the risk of not being able to even explain the purpose of a
change in the patch headers!
In addition section 5.4 explains the purpose of the Signed-off-by: tag line as
discussed in later parts of this document. Due to the importance of the
Signed-off-by: tag line a copy of the description follows:
Signed-off-by: this is a developer's certification that he or she has
the right to submit the patch for inclusion into the [project]. It is
an agreement to the Developer's Certificate of Origin, the full text of
which can be found in
https://github.com/torvalds/linux/blob/master/Documentation/process/submitting-patches.rst[Submitting Patches]
Code without a proper signoff cannot be merged into the mainline.
== Common Errors in Patch and Commit Messages
- Avoid starting the summary line with a capital letter, unless the component
being referred to also begins with a capital letter.
- Don't have one huge patch, split your change into logical subparts. It's
easier to track down problems afterward using tools such as git bisect. It
also makes it easy for people to cherry-pick changes into things like stable
branches.
- Don't simply translate your change into English for a commit log. The log
"Change compare from zero to one" is bad because it describes only the code
change in the patch; we can see that from reading the patch itself. Let the
code tell the story of the mechanics of the change (as much as possible), and
let your comment tell the other details -- i.e. what the problem was, how it
manifested itself (symptoms), and if necessary, the justification for why the
fix was done in manner that it was. In other words, the long commit message
must describe *why* the change was needed (instead of what has changed).
- Don't start your commit log with "This patch..." -- we already know it is a
patch.
- Don't repeat your short log in the long log. If you really really don't have
anything new and informational to add in as a long log, then don't put a long
log at all. This should be uncommon -- i.e. the only acceptable cases for no
long log would be something like:
"Documentation/README: Fix spelling mistakes".
- Don't put absolute paths to source files that are specific to your site.
- Always use the most significant ramification of the change in the words of
your subject/shortlog. For example, don't say "fix compile warning in foo"
when the compiler warning was really telling us that we were dereferencing
complete garbage off in the weeds that could in theory cause an OOPS under
some circumstances. When people are choosing commits for backports to stable
or distro kernels, the shortlog will be what they use for an initial sorting
selection. If they see "Fix possible OOPS in...." then these people will look
closer, whereas they most likely will skip over simple warning fixes.
- Don't put in the full 20 or more lines of a backtrace when really it is just
the last 5 or so function calls that are relevant to the crash/fix. If the
entry point, or start of the trace is relevant (i.e. a syscall or similar),
you can leave that, and then replace a chunk of the intermediate calls in the
middle with a single [...]
- Don't include timestamps or other unnecessary information, unless they are
relevant to the situation (i.e. indicating an unacceptable delay in a driver
initialization etc.)
- Don't use links to temporary resources like pastebin and friends. The commit
message may be read long after this resource timed out.
- Don't reference mirrors, but instead always reference original authoritative
sources.
- Avoid punctuation in the short log.
== Documenting
- References to wikipedia are not permitted.
=== Documenting the code
- Allow doxygen to use all its default behaviors to identify tagged
information but where a doxygen tag must be specified use @
- The first line is by default the brief summary.
- The next paragraph is by default the detailed summary
- Doxygen shall generate the layout, no additional formatting should be inserted
- Normal comment sections should be before the code block and start with
/** on its own line and finish with */ on its own line. The exception
to this rule is a case where the comment is very small, for example
[source,doxygen]
----
/** macro description */
#define SOME_MACRO 0
----
- Commenting on the end of a line for macros and struct members is allowed
using: /**< <text> */ for example
[source,doxygen]
----
#define SOME_MACRO 0 /**< <text> */
----
- Files should start with a files description using @file
- Functions should specify their parameters with @param[in] and @param[out]
- Functions return values should all be specified using @return or @retval
- There should be no doxygen warnings or errors generated.
=== Documenting the user docs
- Users guides are stored in asciidoctor format in the odp/docs directory and in
sub directories of it as appropriate.
- ODP code references such as types and enums are highlighted using the
` syntax. For example text referring to the type odp_pktio_t would decorate the
type thus:
[source,asciidoc]
----
`odp_pktio_t`
----
- Section heading use the = syntax. For example:-
[source,asciidoc]
----
== Level 1
Text.
=== Level 2
Text.
----
- Code and scripting excerpts are decorated with the block syntax:-
[source,asciidoc]
----
.Optional Title
[source,perl]
----
<code here>
----
----
- Images are decorated with :-
[source,asciidoc]
----
.Optional Title
image::../<image name>.svg[align="center"]
----
- The images are stored in the doc/images directory as svg files, src for image
generators such as .gv and .msg should also render to .svg
- Body text shall wrap at the 80 char point.
- No warnings may be generated by the asciidoctor tool.
|
