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 dual licensed under the terms of the 10license 11 12 * BSD 2-Clause (The BSD 2-Clause License) 13 14and 15 16 * GPL v2+ (The GNU General Public License 2.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, the GNU GCC and 28the LLVM C-compiler (CLang) are supported. The Windows systems are not 29currently supported (until someone is creating support for it). 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. 38No matter if you just have a simple question, some specific problem or 39want to discuss some patches, please write it to the mailing list. Please 40avoid personal mailings to the maintainer (or some other contributor) if 41your questions will probably be in the interest of other users too. 42You can subscribe to the list here: 43 44 https://lists.sourceforge.net/lists/listinfo/libcoap-developers 45 46The archive of the list can be found on: 47 48 https://sourceforge.net/p/libcoap/mailman/libcoap-developers 49 503. Starting contributing 51~~~~~~~~~~~~~~~~~~~~~~~~ 52As written above libcoap is maintained with the Git tools so you should be 53familiar with the various git commands. 54The libcoap project is using just two main branches, the 'master' branch is 55holding the point releases, all the development process is going on in the 56'develop' branch. 57To start any contributing you first have to clone the git tree from the main 58repository on GitHub: 59 60 git clone https://github.com/obgm/libcoap.git 61 624. Working on the source 63~~~~~~~~~~~~~~~~~~~~~~~~ 64As one golden rule you should work on improvements within *your* own local 65development branch! To do so you have to first checkout the 'develop' branch 66as local branch and then start on top on this branch your own branch. So 67create (or better say checkout) the local 'develop' branch: 68 69 cd libcoap 70 git checkout develop origin/develop 71 72Now you can simply start your own local branch (for example 'my-develop') 73with the 'origin/develop' as parent so you can later create the patches 74against the the upstream development branch: 75 76 git checkout -b my-develop 77 78At this point you can now work as known with git, modify the source, commit 79the changes, amend if needed and test your work. 80At some point you will have to generate patches to post them on the mailing 81list (and/or push your changes into your public Git tree). It's a good idea to 82post your patch series on the mailing list so other contributors will see your 83work and give further suggestions or discuss your work. 84 85To be able to send a patch series you will now create the series itself as 86single patches, this will be going easy with the 'git format-patch' command 87against the 'develop' branch, remind this is the upstream main development 88branch. 89To not mix up your series with probably unrelated patches let git place the 90patches within a defined directory. Also, while create the patches, tell git to 91create a cover letter patch so you can append some introducing words that will 92hold probably explanations why you create the patches in the way you have done. 93 94 git format-patch --cover-letter -o ../patches4libcoap 95 96This command will create a patch series in ../patches4libcoap where you find a 97patch named '0000-cover-letter.patch'. Please modify this patch with some 98useful information's for the mailing list. After finish this you now can send 99your patches to libcoap-developers@lists.sourceforge.net 100 101 git send-email ../patches4libcoap/* --to=libcoap-developers@lists.sourceforge.net 102 1035. Coding rules 104~~~~~~~~~~~~~~~ 105As every FOSS project the libcoap project needs also some rules for coding. 106There are loss but the main of them are important! 107 1085.1 License and Copyright 109------------------------- 110Every new file must contain a license and the copyright holder(s). Please 111take a look into existing files and adopt the needed changes to your new 112file(s). 113 1145.2 Source Code Indentation 115--------------------------- 116* For better reading the indentation is set to 2 characters as spaces, this 117 is depended on the often used nested functions like 'if-else'. Don't use 118 TABs any there! Avoid trailing white spaces at the end of a line. 119 It's appropriate to set up a modline like this one at first line within 120 the source file: 121 122--8<---- 123/* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 * -*- */ 124--->8-- 125 126* Single lines within the source code should not be longer then 78 127 characters. 128 129* If there a functions with a lot of parameters that do not fit into the above 130 rule split the declaration (in the *.h) and the implementation (in the *.c) 131 into single lines per parameter. For example like this (from src/block.c): 132 133--8<---- 134int 135coap_add_block(coap_pdu_t *pdu, 136 unsigned int len, 137 const unsigned char *data, 138 unsigned int block_num, 139 unsigned char block_szx); 140--->8-- 141 1425.3 Source Code Documentation 143----------------------------- 144* A useful source code documentation is mandatory. Mostly to be done within the 145 source code files, but more complex description should be done in extra 146 README files. 147 148* Please set up/adjust the doxygen documentation if you create new functions or 149 change existing functions. The doxygen documentation has to be done in the 150 header files as they are the public part of the libcoap and only use the 151 @-syntax for doxygen commands (akin to javadoc). 152 1535.4 API Changes 154--------------- 155* Never break the API! 156 Don't remove old functions and if there some changes are needed in some kind 157 always provide a wrapper for the old call to let the library be backward 158 compatible and mark the old function as @deprecated in the doxygen comment. 159 Please discuss needed changes on the mailing list. 160 1615.5 Patches and Commits 162----------------------- 163* Git commits must be atomic and contain a declarative subject line (max 50 164 characters if possible) and a body for a statement if needed. 165 Use the possibility to write a good explanation why your patch/commit is 166 handle the changes in the way you have done. Remind that other user can 167 read your code but not necessary understand why the code is written this 168 way. Don't use something to generic like "bugfix commit". 169 170* A patch/commit or a series of patches/commits have to ensure that the 171 whole project is able to build up every thing, in short: Do not break 172 any make target and test your work. 173 174* Every patch/commit should handle one single logical change. If more than 175 one patch/commit is needed for a change explain it, respect the point 176 above. If your subject line become much larger than 50 characters then 177 typically your patch is to big for one single commit. 178 179* Commit message should begin with a submodule or unit the commit is for. By 180 this your commit message helps to find thematic other changes. If you have 181 to search and find something with 'git log | grep [foo]' you will see why 182 this is useful. Examples: 183 184 rd.c: Fixed type-specifier warning 185 Makefile.am: Added missing src/address.c 186 address.[hc]: make coap_address_equals() not inline on POSIX 187 1886. Where to start contributing? 189~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 190There are various things you could starting on to contribute, the best 191is you simply pick up an issue you blindly see and just improve the 192situation. Please take also a look into the file TODO and choose a point 193from there or point the maintainer to add other things here too. 194 195* Documentation 196We are always lacking on a better documentation on the source code, so 197maybe you can improve the doxygen documentation. 198Also a good documentation on the usage of the libcoap and the example 199binaries is always improvable. So we appreciate any help on this. 200 201* Man Pages 202The source is providing some example binaries which originally just should show 203how the libcoap can be used. Right now these binaries are fully usable and 204quite more than simple examples on a system. There are man pages for these 205binaries available, if you found there is a improvement needed please do so and 206write to the mailing list explained in section 2. 207Maybe you can write up some good HowTo's on the usage for these binaries. A man 208page for the library itself would be also a improvement. 209 210* HowTo's 211The libcoap library has now a lot of functions you can use. 212Unfortunately there is no good user guide on how to use the libcoap in 213any external project. This means there is no HowTo or CheatSheet for a 214programming person available. You want to write up something? 215 216* missed Functionality 217There are some features that are still missing inside the libcoap. For 218example some DTLS implementations and proxy functionality. 219 220
