]>
Commit | Line | Data |
---|---|---|
f6ee5b52 DL |
1 | # Developing for PROJECT (DRAFT) |
2 | ||
4765f35e | 3 | [TOC] |
f6ee5b52 DL |
4 | |
5 | ## Git Structure | |
6 | ||
7 | The master Git for PROJECT resides on Github at | |
4765f35e | 8 | [https://github.com/PROJECT/XXX](https://github.com/PROJECT/XXX) |
f6ee5b52 | 9 | |
9b7939d9 DL |
10 | ![git branches continually merging to the left from 3 lanes; float-right](doc/git_branches.svg |
11 | "git branch mechanics") | |
12 | ||
f6ee5b52 DL |
13 | There are 3 main branches for development and a release branch for each |
14 | major release. | |
15 | ||
16 | New contributions are done against the head of the Develop branch. The CI | |
17 | systems will pick up the Github Pull Requests or the new patch from | |
18 | Patchwork, run some basic build and functional tests and will merge them | |
19 | into the branch automatically on success. | |
20 | ||
21 | Code on the develop branch will then be further tested and reviewed by the | |
22 | community and merged to master on a regular interval. | |
23 | ||
24 | For each major release (1.0, 1.1 etc) a new release branch is created based | |
25 | on the master. | |
26 | ||
27 | ||
28 | ## Programming language, Tools and Libraries | |
29 | ||
30 | The core of PROJECT is written in C (gcc or clang supported). A few | |
31 | non-essential scripts are implemented in Perl and Python. PROJECT requires | |
32 | the following tools to build distribution packages: automake, autoconf, | |
33 | texinfo, libtool and gawk and various libraries (i.e. libpam and libjson-c). | |
34 | ||
35 | If your contribution requires a new library or other tool, then please | |
36 | highlight this in your description of the change. Also make sure it’s | |
37 | supported by all PROJECT platform OSes or provide a way to build without the | |
38 | library (potentially without the new feature) on the other platforms. | |
39 | ||
40 | Documentation should be written in Tex (.texi) or Markdown (.md) format with | |
41 | preference on Markdown. | |
42 | ||
43 | ||
44 | ## Before Submitting your changes | |
45 | ||
4765f35e DL |
46 | * Format code (see [Code Styling requirements](#code-styling-requirements)) |
47 | * Verify and acknowledge license (see [License for contributions](#license-for-contributions)) | |
f6ee5b52 | 48 | * Test building with various configurations: |
4765f35e | 49 | * `buildtest.sh` |
f6ee5b52 | 50 | * Verify building source distribution: |
4765f35e | 51 | * `make dist` (and try rebuilding from the resulting tar file) |
f6ee5b52 | 52 | * Run DejaGNU unit tests: |
4765f35e | 53 | * `make test` |
f6ee5b52 DL |
54 | * Document Regression Runs and plans for continued maintenance of the feature |
55 | ||
56 | ### Changelog | |
57 | ||
58 | The changelog will be the base for the release notes. A changelog entry for | |
59 | your changes is usually not required and will be added based on your commit | |
60 | messages by the maintainers. However, you are free to include an update to | |
61 | the changelog with some better description. The changelog will be the base | |
62 | for the release notes. | |
63 | ||
64 | ||
65 | ## Submitting Patches and Enhancements | |
66 | ||
67 | ### License for contributions | |
68 | ||
69 | PROJECT is under a “GPLv2 or later” license. Any code submitted must be | |
70 | released under the same license (preferred) or any license which allows | |
71 | redistribution under this GPLv2 license (eg MIT License). | |
72 | ||
73 | ### Signed-off required | |
74 | ||
75 | Submissions to PROJECT require a “Signed-off” in the patch or git commit. | |
76 | We follow the same standard as the Linux Kernel Development. | |
77 | ||
78 | > Developer's Certificate of Origin 1.1 | |
79 | > | |
80 | > By making a contribution to this project, I certify that: | |
81 | > | |
82 | > (a) The contribution was created in whole or in part by me and I | |
83 | > have the right to submit it under the open source license | |
84 | > indicated in the file; or | |
85 | > | |
86 | > (b) The contribution is based upon previous work that, to the best | |
87 | > of my knowledge, is covered under an appropriate open source | |
88 | > license and I have the right under that license to submit that | |
89 | > work with modifications, whether created in whole or in part | |
90 | > by me, under the same open source license (unless I am | |
91 | > permitted to submit under a different license), as indicated | |
92 | > in the file; or | |
93 | > | |
94 | > (c) The contribution was provided directly to me by some other | |
95 | > person who certified (a), (b) or (c) and I have not modified | |
96 | > it. | |
97 | > | |
98 | > (d) I understand and agree that this project and the contribution | |
99 | > are public and that a record of the contribution (including all | |
100 | > personal information I submit with it, including my sign-off) is | |
101 | > maintained indefinitely and may be redistributed consistent with | |
102 | > this project or the open source license(s) involved. | |
103 | ||
104 | #### Using this Process | |
105 | ||
106 | We have the same requirements for using the signed-off-by process as the Linux | |
107 | kernel. In short, you need to include a signed-off-by tag in every patch: | |
108 | ||
109 | * `Signed-off-by:` this is a developer's certification that he or she has the | |
110 | right to submit the patch for inclusion into the project. It is an agreement to | |
111 | the Developer's Certificate of Origin (above). Code without a proper signoff | |
112 | cannot be merged into the mainline. | |
113 | ||
114 | Please make sure to have a `Signed-off-by:` in each commit/patch or the patches | |
115 | will be rejected until this is added. | |
116 | ||
117 | If you are unfamiliar with this process, you should read the [official policy | |
118 | at kernel.org](http://www.kernel.org/doc/Documentation/SubmittingPatches) and | |
119 | you might find this article about [participating in the Linux community on the | |
120 | Linux Foundation | |
121 | website](http://www.linuxfoundation.org/content/how-participate-linux-community-0) | |
122 | to be a helpful resource. | |
123 | ||
124 | ||
4765f35e | 125 | ### Code submission - Github Pull Request (Strongly Preferred) |
f6ee5b52 DL |
126 | |
127 | Preferred submission of code is by using a Github Pull Request against the | |
128 | Develop branch. Code submitted by Pull Request will have an email generated to | |
129 | the PROJECT-devel mailing list for review and the submission will be | |
130 | automatically tested by one or more CI systems. Only after this test succeeds | |
131 | (and the submission is based on the head of the develop branch), then it will | |
132 | be automatically merged into the develop branch. In case of failed tests, it is | |
133 | up to the submitter to either amend the request with further commits or close, | |
134 | fix and create a new pull request. | |
135 | ||
136 | Further (manual) code review and discussion happens after the merge into the | |
137 | develop branch. | |
138 | ||
139 | ||
4765f35e | 140 | ### Code submission - Mailing Patch to PROJECT-Devel list |
f6ee5b52 DL |
141 | |
142 | As an alternative submission, a patch can be mailed to the PROJECT-Devel | |
143 | mailing list. Preferred way to send the patch is using git send-mail. Patches | |
144 | received on the mailing list will be picked up by Patchwork and tested against | |
145 | the latest develop branch. After a further ACK by someone on the mailing list, | |
146 | the patch is then merged into the develop branch. | |
147 | ||
148 | Further (manual) code review and discussion happens after the merge into the | |
149 | develop branch. | |
150 | ||
4765f35e | 151 | #### Sending patch to mailing list |
f6ee5b52 DL |
152 | |
153 | The recommended way to send the patch (or series of NN patches) to the list is | |
154 | by using ‘git send-email’ as follows (assuming they are the most recent NN | |
155 | commit(s) in your git history: | |
156 | ||
157 | ``` | |
158 | git send-email -NN --annotate --to=XXX-Devel@XXX.org | |
159 | ``` | |
160 | ||
161 | If your commits do not already contain a `Signed-off-by` line, then use the | |
162 | following version to add it (after making sure to be able to agree to the | |
163 | Developer Certificate of Origin as outlined above): | |
164 | ||
165 | ``` | |
166 | git send-email -NN --annotate --signoff --to=XXX-Devel@XXX.org | |
167 | ``` | |
168 | ||
169 | Submitting multi-commit patches as a Github Pull Request is strongly encouraged | |
170 | and will allow your changes to merge faster | |
171 | ||
172 | ||
173 | ## After submitting your changes | |
174 | ||
175 | * Watch for Continuous Integration (CI) Test results | |
176 | * You should automatically receive an email with the test results within | |
177 | less than 2 hrs of the submission. If you don’t get the email, then check | |
178 | status on the github pull request (if submitted by pull request) or on | |
4765f35e DL |
179 | Patchwork at |
180 | [https://patchwork.PROJECT.org](https://patchwork.PROJECT.org) (if | |
181 | submitted as patch to mailing list). | |
f6ee5b52 | 182 | * Please notify PROJECT-Devel mailing list if you think something doesn’t |
4765f35e | 183 | work |
f6ee5b52 DL |
184 | * If the tests failed: |
185 | * In general, expect the community to ignore the submission until the tests | |
186 | pass. | |
187 | * It is up to you to fix and resubmit. | |
188 | * This includes fixing existing dejagnu (“make test”) tests if your | |
189 | changes broke or changed them. | |
190 | * It also includes fixing distribution packages for the failing | |
191 | platforms (ie if new libraries are required) | |
192 | * Feel free to ask for help on PROJECT-Devel list | |
193 | * Go back to the submission process and repeat until the tests pass. | |
194 | * If the tests pass: | |
195 | * If the changes are done as a pull request, then they should be | |
196 | automatically merged to the develop branch. | |
197 | * Changes sent to mailing list require a manual ACK to be merged and should | |
198 | be merged within 2 weeks. If you don’t see the merge or any | |
199 | reason/discussion on PROJECT-Devel, then please ask. | |
200 | * Watch out for questions on the mailing list. At this time there will be a | |
201 | manual code review and further (longer) tests by various community members. | |
202 | * Your submission is done once it is merged to the master branch. (which should | |
203 | happen every few weeks from the develop branch) | |
204 | ||
205 | ||
206 | ## Code Styling requirements | |
207 | ||
208 | ### File header required for new files added | |
209 | ||
4765f35e DL |
210 | New files need to have a Copyright header (see [License for |
211 | contributions](#license-for-contributions) above) added to the file. Preferred | |
212 | form of the header is as follows: | |
f6ee5b52 DL |
213 | |
214 | ``` | |
215 | /* | |
216 | Title/Function of file | |
217 | Copyright (C) 2016 Author’s Name | |
218 | ||
219 | This program is free software; you can redistribute it and/or modify | |
220 | it under the terms of the GNU General Public License as published by | |
221 | the Free Software Foundation; either version 2 of the License, or | |
222 | (at your option) any later version. | |
223 | ||
224 | This program is distributed in the hope that it will be useful, but | |
225 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
226 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
227 | General Public License for more details. | |
228 | ||
229 | You should have received a copy of the GNU General Public License | |
230 | along with this program; see the file COPYING; if not, write to the | |
231 | Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, | |
232 | MA 02110-1301 USA | |
233 | */ | |
4765f35e DL |
234 | |
235 | #include <zebra.h> | |
f6ee5b52 DL |
236 | ``` |
237 | ||
238 | ### Adding Copyright claims to already existing file | |
239 | ||
240 | When adding copyright claims for modifications to an existing file, please | |
241 | preface the claim with "Portions: " on a line before it and indent the | |
242 | "Copyright ..." string. If such a case already exists, add your indented claim | |
243 | immediately after. E.g.: | |
244 | ||
245 | ``` | |
246 | Portions: | |
247 | Copyright (C) 2010 Entity A .... | |
248 | Copyright (C) 2016 Your name [optional brief change description] | |
249 | ``` | |
250 | ||
251 | ### Code styling / format | |
252 | ||
253 | GNU coding standards apply. Indentation follows the result of invoking GNU | |
254 | indent (as of 2.2.8a) with the `-nut -nfc1` arguments. | |
255 | ||
256 | ``` | |
257 | indent -nut -nfc1 file_for_submission.c | |
258 | ``` | |
259 | ||
260 | Please don’t reformat existing files (or only sections modified by your | |
261 | changes), even if they don’t follow the standard. This makes it very hard to | |
262 | highlight the changes | |
263 | ||
264 | ### Changing / Deprecate an existing exported interface | |
265 | ||
266 | If changing an exported interface, please try to deprecate the interface in an | |
267 | orderly manner. If at all possible, try to retain the old deprecated interface | |
268 | as is, or functionally equivalent. Make a note of when the interface was | |
269 | deprecated and guard the deprecated interface definitions in the header file, | |
270 | i.e.: | |
271 | ||
272 | ``` | |
273 | /* Deprecated: 20050406 */ | |
274 | #if !defined(QUAGGA_NO_DEPRECATED_INTERFACES) | |
275 | #warning "Using deprecated <libname> (interface(s)|function(s))" | |
276 | ... | |
277 | #endif /* QUAGGA_NO_DEPRECATED_INTERFACES */ | |
278 | ``` | |
279 | ||
280 | This is to ensure that the core Quagga sources do not use the deprecated | |
281 | interfaces (you should update Quagga sources to use new interfaces, if | |
282 | applicable), while allowing external sources to continue to build. Deprecated | |
283 | interfaces should be excised in the next unstable cycle. | |
284 | ||
285 | Note: If you wish, you can test for GCC and use a function marked with the | |
286 | `deprecated` attribute. However, you must provide the warning for other | |
287 | compilers. If changing or removing a command definition, ensure that you | |
288 | properly deprecate it - use the `_DEPRECATED` form of the appropriate `DEFUN` | |
289 | macro. This is critical. Even if the command can no longer function, you MUST | |
290 | still implement it as a do-nothing stub. | |
291 | ||
292 | Failure to follow this causes grief for systems administrators, as an upgrade | |
293 | may cause daemons to fail to start because of unrecognised commands. Deprecated | |
294 | commands should be excised in the next unstable cycle. A list of deprecated | |
295 | commands should be collated for each release. | |
296 | ||
297 | ||
298 | ### Compile-Time conditional code | |
299 | ||
300 | Many users access PROJECT via binary packages from 3rd party sources; | |
301 | compile-time code puts inclusion/exclusion in the hands of the package | |
302 | maintainer. Please think very carefully before making code conditional at | |
303 | compile time, as it increases regression testing, maintenance burdens, and user | |
304 | confusion. In particular, please avoid gratuitous --enable-… switches to the | |
305 | configure script - typically code should be good enough to be in PROJECT, or it | |
306 | shouldn’t be there at all. | |
307 | ||
308 | When code must be compile-time conditional, try have the compiler make it | |
309 | conditional rather than the C pre-processor - so that it will still be checked | |
310 | by the compiler, even if disabled. I.e. this: | |
311 | ||
312 | ``` | |
313 | if (SOME_SYMBOL) | |
314 | frobnicate(); | |
315 | ``` | |
316 | ||
317 | rather than | |
318 | ||
319 | ``` | |
320 | #ifdef SOME_SYMBOL | |
321 | frobnicate (); | |
322 | #endif /* SOME_SYMBOL */ | |
323 | ``` | |
324 | ||
325 | Note that the former approach requires ensuring that `SOME_SYMBOL` will be | |
326 | defined (watch your `AC_DEFINE`s). |