$treeview $search $mathjax $extrastylesheet
librsync
2.3.1
$projectbrief
|
$projectbrief
|
$searchbox |
00001 # Contributing to librsync {#page_contributing} 00002 00003 Instructions and conventions for people wanting to work on librsync. Please 00004 consider these guidelines even if you're doing your own fork. 00005 00006 ## Code Style 00007 00008 The prefered style for code is equivalent to using GNU indent with the 00009 following arguments; 00010 00011 ```Shell 00012 $ indent -linux -nut -i4 -ppi2 -l80 -lc80 -fc1 -fca -sob 00013 ``` 00014 00015 The preferred style for non-docbook comments are as follows; 00016 00017 ```C 00018 00019 /*= 00020 | A short poem that 00021 | shall never ever be 00022 | reformated or reindented 00023 */ 00024 00025 /* Single line comment indented to match code indenting. */ 00026 00027 /* Blank line delimited paragraph multi-line comments. 00028 00029 Without leading stars, or blank line comment delimiters. */ 00030 00031 int a; /* code line comments */ 00032 ``` 00033 00034 The preferred style for docbook comments is javadoc with autobrief as 00035 follows; 00036 00037 ```C 00038 /** /file file.c 00039 * Brief summary paragraph. 00040 * 00041 * With blank line paragraph delimiters and leading stars. 00042 * 00043 * /param foo parameter descriptions... 00044 * 00045 * /param bar ...in separate blank-line delimited paragraphs. 00046 * 00047 * Example:/code 00048 * code blocks that will never be reformated. 00049 * /endcode 00050 * 00051 * Without blank-line comment delimiters. */ 00052 00053 int a; /**< brief attribute description */ 00054 int b; /**< multiline attribute description 00055 * 00056 * With blank line delimited paragraphs.*/ 00057 ``` 00058 00059 There is a `make tidy` target that will use GNU indent to reformat all 00060 code and non-docbook comments, doing some pre/post processing with sed 00061 to handle some corner cases indent doesn't handle well. 00062 00063 There is also a `make tidyc` target that will reformat all code and 00064 comments with https://github.com/dbaarda/tidyc. This will also 00065 correctly reformat all docbook comments, equivalent to running tidyc 00066 with the following arguments; 00067 00068 ```Shell 00069 $ tidyc -R -C -l80 00070 ``` 00071 00072 ## Pull requests 00073 00074 Fixes or improvements in pull requests are welcome. Please: 00075 00076 - [ ] Send small PRs that address one issues each. 00077 00078 - [ ] Update `NEWS.md` to say what you changed. 00079 00080 - [ ] Add a test as a self-contained C file in `tests/` that passes or fails, 00081 and is hooked into `CMakeLists.txt`. 00082 00083 - [ ] Keep the code style consistent with what's already there, especially in 00084 keeping symbols with an `rs_` prefix. 00085 00086 00087 ## NEWS 00088 00089 [NEWS.md](NEWS.md) contains a list of user-visible changes in the library between 00090 releases version. This includes changes to the way it's packaged, 00091 bug fixes, portability notes, changes to the API, and so on. 00092 00093 Add 00094 and update items under a "Changes in X.Y.Z" heading at the top of 00095 the file. Do this as you go along, so that we don't need to work 00096 out what happened when it's time for a release. 00097 00098 ## Tests 00099 00100 Please try to update docs and tests in parallel with code changes. 00101 00102 ## Releasing 00103 00104 If you are making a new tarball release of librsync, follow this checklist: 00105 00106 * NEWS.md - make sure the top "Changes in X.Y.Z" is correct, and the date is 00107 correct. Make sure the changes since the last release are documented. 00108 00109 * `CMakeLists.txt` - version is correct. 00110 00111 * `librsync.spec` - make sure version and URL are right. 00112 00113 * Run `make all doc check` in a clean checkout of the release tag. Also check 00114 the travis-cl check status of the last commit on github. 00115 00116 * Draft a new release on github, typing in the release details including an 00117 overview, included changes, and known issues. The overview should give an 00118 indication of the magnitude of the changes and their impact, and the 00119 relative urgency to upgrade. The included changes should come from the 00120 NEWS.md for the release. It's probably easiest to copy and edit the previous 00121 release. 00122 00123 * After creating the release, download the tar.gz version, edit the release, 00124 and re-upload it. This ensures that the release includes a stable tarball 00125 (See https://github.com/librsync/librsync/issues/146 for details). 00126 00127 Test results for builds of public github branches are at 00128 https://travis-ci.org/librsync/librsync.