1 ####################################################### 2 # Developer information for contributing to libcoap # 3 ####################################################### 4 51. The basics 6~~~~~~~~~~~~~ 7The libcoap project is a FOSS project that is dual licensed. The maintainer 8for the libcoap is Olaf Bergmann <bergmann@tzi.org>. 9Any contributions have to be made under the terms of the 10license 11 12 * BSD 2-Clause (The BSD 2-Clause License) 13 14Contributions made up to 2017-06-01 have been made under the dual 15license model BSD 2-Clause and GPL v2+ (The GNU General Public License 162.0 or later). 17 18The used VCS for libcoap is Git, the main repository is living on GitHub. 19You can clone (or fork directly on GitHub) on the repository site: 20 21 https://github.com/obgm/libcoap 22 23Please refer also to the libcoap website for additional information 24 25 https://libcoap.net/ 26 27The build environment is grounded on the classical autotools or CMake, the 28GNU GCC and the LLVM C-compiler (CLang) are supported. The Windows VS build 29systems are supported. 30 31Doxygen is used for creating a HTML based online documentation of the 32libcoap library. 33 342. Communications 35~~~~~~~~~~~~~~~~~ 36The main discussion and development platform for libcoap is the mailing list 37on Sourceforge. 38 39No matter if you just have a simple question, some specific problem or 40want to discuss some patches, please write it to the mailing list. Please 41avoid personal mailings to the maintainer (or some other contributor) if 42your questions will probably be in the interest of other users too. 43You can subscribe to the list here: 44 45 https://lists.sourceforge.net/lists/listinfo/libcoap-developers 46 47The archive of the list can be found on: 48 49 https://sourceforge.net/p/libcoap/mailman/libcoap-developers 50 51Alternatively, Issues can be raised at https://github.com/obgm/libcoap/issues 52 533. Starting contributing 54~~~~~~~~~~~~~~~~~~~~~~~~ 55As written above, libcoap is maintained with the Git tools so you should be 56familiar with the various git commands. 57 58The libcoap project is using just two main branches, the 'main' branch is 59holding the point releases, all the development process is going on in the 60'develop' branch. 61 62To start any contributing you first have to clone the git tree from the main 63repository on GitHub: 64 65 git clone https://github.com/obgm/libcoap.git 66 674. Working on the source 68~~~~~~~~~~~~~~~~~~~~~~~~ 69As one golden rule you should work on improvements within *your* own local 70development branch! To do so you have to first checkout the 'develop' branch 71as local branch and then start on top on this branch your own branch. So 72create (or better say checkout) the local 'develop' branch: 73 74 cd libcoap 75 git checkout develop origin/develop 76 77Now you can simply start your own local branch (for example 'my-develop') 78with the 'origin/develop' as parent so you can later create the patches 79against the the upstream development branch: 80 81 git checkout -b my-develop 82 83At this point you can now work with git, modify the source, commit 84the changes, amend if needed and test your work. 85 86At some point you will have to generate patches to post them on the mailing 87list (and/or push your changes into your public Git tree). Multiple commits 88for your branch should be squash'ed into a single commit. This can be done 89one of two ways. 90 91Way One: Push your changes to the github repository. 92 93 git push origin my-develop 94 95Then go to https://github.com/obgm/libcoap/pulls and create your pull request 96for others to review. If changes are needed, then commit and squash changes 97and push the (forced) changes again. 98 99 git push -f origin my-develop 100 101Way Two: Post your patch series on the mailing list so other contributors 102will see your work and give further suggestions or discuss your work. 103 104To be able to send a patch series you will now create the series itself as 105single patches, this will be going easy with the 'git format-patch' command 106against the 'develop' branch, remember this is the upstream primary 107development branch. 108 109To not mix up your series with probably unrelated patches let git place the 110patches within a defined directory. Also, while create the patches, tell git to 111create a cover letter patch so you can append some introducing words that will 112hold probably explanations why you create the patches in the way you have done. 113 114 git format-patch --cover-letter -o ../patches4libcoap 115 116This command will create a patch series in ../patches4libcoap where you find a 117patch named '0000-cover-letter.patch'. Please modify this patch with some 118useful information's for the mailing list. After finish this you now can send 119your patches to libcoap-developers@lists.sourceforge.net 120 121 git send-email ../patches4libcoap/* --to=libcoap-developers@lists.sourceforge.net 122 1235. Coding rules 124~~~~~~~~~~~~~~~ 125As every FOSS project the libcoap project needs also some rules for coding. 126There are lots but the main ones following are important! 127 1285.1 pre-commit 129-------------- 130pre-commit is used to check the the syntax of *.c and *.h files according to 131the libcoap coding rules. The files are checked on github for every 'git push', 132and can be locally checked if pre-commit is installed for every 'git commit'. 133 134$ cd libcoap 135$ pip install pre-commit 136$ pre-commit install --allow-missing-config 137 1385.2 License and Copyright 139------------------------- 140Every new file must contain a license and the copyright holder(s). Please 141take a look into existing files and adopt the needed changes to your new 142file(s). 143 1445.3 Source Code Indentation 145--------------------------- 146* For better reading the indentation is set to 2 characters as spaces, this 147 is depended on the often used nested functions like 'if-else'. Don't use 148 TABs any where (apart from Makefile's indenting where TABs are mandatory)! 149 Avoid trailing white spaces at the end of a line. 150 It's appropriate to set up a modline like this one at first line within 151 the source file: 152 153--8<---- 154/* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 155--->8-- 156 157* For functions defined in *.h files, the function return type should be 158 defined on the same line as the function name declaration. For functions 159 defined in *.c files, the function return type should be defined on the 160 previous line (for both declarations and implementations). 161 162* Single lines within the source code should not be longer then 78 163 characters. 164 165* If there are functions with a lot of parameters that do not fit into the above 166 rule split the declaration (in the *.h) and the implementation (in the *.c) 167 into single lines per parameter. Each parameter should be aligned with the 168 first defined parameter. For example like this (from src/coap_block.c): 169 170--8<---- 171int 172coap_add_block(coap_pdu_t *pdu, 173 unsigned int len, 174 const unsigned char *data, 175 unsigned int block_num, 176 unsigned char block_szx) { 177--->8-- 178 1795.4 Source Code Documentation 180----------------------------- 181* A useful source code documentation is mandatory. Mostly to be done within the 182 source code files, but more complex description should be done in extra 183 README files. 184 185* Please set up/adjust the doxygen documentation if you create new functions or 186 change existing functions. The doxygen documentation has to be done in the 187 header files as they are the public part of the libcoap and only use the 188 @-syntax for doxygen commands (akin to javadoc). 189 1905.5 API Changes 191--------------- 192* Never break the API! 193 Don't remove old functions and if there some changes are needed in some kind 194 always provide a wrapper for the old call to let the library be backward 195 compatible and mark the old function as @deprecated in the doxygen comment. 196 Please discuss needed changes on the mailing list. 197 1985.6 Patches and Commits 199----------------------- 200* Git commits must be atomic and contain a declarative subject line (max 50 201 characters if possible) and a body for a statement if needed. 202 Use the opportunity to write a good explanation why your patch/commit is to 203 handle the changes in the way you have done. Remember that other users can 204 read your code but not necessary understand why the code is written this 205 way. Don't use something to generic like "bugfix commit". 206 207* A patch/commit or a series of patches/commits have to ensure that the 208 whole project is able to build up every thing, in short: Do not break 209 any make target and test your work. 210 211* Every patch/commit should handle one single logical change. If more than 212 one patch/commit is needed for a change explain it, respect the point 213 above. If your subject line become much larger than 50 characters then 214 typically your patch is to big for one single commit. 215 216* Commit message should begin with a submodule or unit the commit is for. 217 Doing this in your commit message helps to find thematic other changes. If 218 you have to search and find something with 'git log | grep [foo]' you will 219 see why this is useful. Examples: 220 221 rd.c: Fixed type-specifier warning 222 Makefile.am: Added missing src/coap_address.c 223 address.[hc]: make coap_address_equals() not inline on POSIX 224 2256. Where to start contributing? 226~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 227There are various things you could starting on to contribute, the best 228is you simply pick up an issue you can easily see and just improve the 229situation. Please take also a look into the file TODO and choose a point 230from there or point the maintainer to add other things here too. 231 232* Documentation 233We always need better documentation on the source code, as well as improving 234the doxygen documentation in the header files. Updating the man pages for 235missing functions helps. 236Also updated documentation on the usage of the libcoap and the example 237binaries is always useful. So we appreciate any help on this. 238 239* Manual Pages for example binaries 240Manual pages are provided for the example binaries which have become more 241complex over time with a variety of configuration options. It is possible 242to work out how to use particular application functionality by reading the 243examples source code. Improving documentation for usage would be useful. 244 245* Manual Pages for public API 246As well as the doxygen documentation, manual pages are being written for the 247public licoap API where functions are defined, what the parameters mean as 248well as providing simple coding examples. These manual pages are also 249embedded in the doxygen output, the latest copy of which can be seen at 250https://libcoap.net/doc/reference/develop/ 251Updating these manual pages for the missing functions, correcting errors 252or providing simple examples of function usage would be helpful. 253 254* HowTo's 255The libcoap library has now a lot of functions you can use. 256Unfortunately there is no good user guide on how to use the libcoap in 257any external project. This means there is no HowTo or CheatSheet for a 258programming person available. Do you want to write up something? 259 260* Missing functionality 261There are some features that are still missing inside the libcoap. For 262example some DTLS implementations and proxy functionality. 263 264