librsync  2.3.4
CONTRIBUTING.md
1 # CONTRIBUTING
2 
3 Instructions and conventions for people wanting to work on librsync. Please
4 consider these guidelines even if you're doing your own fork.
5 
6 ## Requirements
7 
8 There are a bunch of tools and libraries that are useful for development or
9 that librsync depends on. In addition to the standard cmake/gcc/make/etc C
10 development tools, the following packages are recommended;
11 
12 * libpopt-dev - the cmdline argument parsing library used by rdiff. If this is
13  not available rdiff cannot be compiled, and only the librsync library will
14  be compiled.
15 
16 * libb2-dev - blake2 hash library librsync can use if `USE_LIBB2` is set to
17  `ON` in cmake. If this is not avalable librsync will use its included copy
18  of blake2 (which may be older... or newer).
19 
20 * doxygen - documentation generator used to generate html documentation. If
21  installed `make doc` can be run to generate all the docs.
22 
23 * graphviz - graph generator used by doxygen for generating diagrams. If not
24  installed doxygen will not generate any diagrams.
25 
26 * indent - code reformatter for tidying code. If installed all the code can be
27  tidied with `make tidy`.
28 
29 * [tidyc](https://github.com/dbaarda/tidyc) - extension wrapper for indent
30  that includes better formatting of doxygen comments. If installed code and
31  comments can be tidied with `make tidyc`.
32 
33 * clang-tidy - code lint checker for potential problems. If installed the code
34  can be checked with `make clang-tidy`.
35 
36 * iwyu - `#include` checker and fixer. If installed includes can be checked
37  with `make iwyu`, and automatically fixed with `make iwyu-fix`. Note on some
38  platforms this package is [missing a
39  dependency](https://bugs.launchpad.net/ubuntu/+source/iwyu/+bug/1769334) and
40  also needs `libclang-common-9-dev` to be installed.
41 
42 These can all be installed on Debian/Ubuntu systems by running;
43 
44 ```Shell
45 $ apt-get update
46 $ apt-get install libpopt-dev libb2-dev doxygen graphviz indent clang-tidy iwyu
47 $ git clone https://github.com/dbaarda/tidyc.git
48 $ cp tidyc/tidyc ~/bin
49 ```
50 
51 ### Windows
52 
53 Not all the recommended packages are easily available on windows.
54 [Cygwin](https://cygwin.com/) and [MSYS2](http://msys2.org/) provide a
55 development environment similar to Linux. Some packages can also be found on
56 [Chocolatey](https://chocolatey.org/). For native development using standard
57 MSVC tools, libpopt can be found on [vcpkg](https://vcpkg.io/) and installed
58 by running;
59 
60 ```Shell
61 $ vcpkg update
62 $ vcpkg --triplet x64-windows install libpopt
63 ```
64 
65 For cmake to find the installed libpopt you need to add `-D
66 CMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake` to the cmake
67 cmdline. This configures cmake to correctly search the vcpkg install locations
68 to find libraries.
69 
70 ### MacOS
71 
72 MacOS is generally more similar to Linux than Windows, and several packages
73 are available on homebrew. The libpopt library can be installed by running;
74 
75 ```Shell
76 $ brew update
77 $ brew install popt
78 ```
79 
80 ## Building
81 
82 The minimal instructions to fetch, configure, compile, and test everything
83 using a in-place default Debug build with trace enabled using the internal
84 blake2 implementation is;
85 
86 ```Shell
87 $ git clone https://github.com/librsync/librsync.git
88 $ cd librsync
89 $ cmake .
90 $ make check
91 ```
92 
93 For cmake, `-B` can be used to select a separate build directory, and `-G` can
94 select a different make system. Also the following settings can be changed
95 with `-D <setting>=<value>` arguments when generating the project with cmake;
96 
97 * CMAKE_BUILD_TYPE=(Debug|Release|MinSizeRel|RelWithDebInfo) - the build type
98  to use, which selects compiler options. The default is `Debug`.
99 
100 * CMAKE_C_COMPILER=(cc|gcc|clang|...) - The compiler to use. The default is to
101  auto-detect the available compiler on the platform.
102 
103 * BUILD_RDIFF=(ON|OFF) - Whether to build and test the rdiff executable.
104  Defaults to ON if libpopt is available.
105 
106 * BUILD_SHARED_LIBS=(ON|OFF) - Whether to build dynamic libraries or use
107  static linking. Defaults to ON.
108 
109 * ENABLE_TRACE=(ON|OFF) - Whether to enable trace output in the library and
110  for rdiff using `-v`. Trace output can help with debugging but its a little
111  faster with ENABLE_TRACE=OFF. Defaults to ON for Debug builds, and OFF for
112  others.
113 
114 * USE_LIBB2=(ON|OFF) - Whether to use libb2 instead of the included blake2
115  implementation. Defaults to OFF.
116 
117 So for a Release build in a separate directory using Ninja, clang, static
118 linking, and libb2 with trace enabled, do this instead;
119 
120 ```Shell
121 $ cmake -B build -G Ninja
122  -D CMAKE_C_COMPILER=clang \
123  -D CMAKE_BUILD_TYPE=Release \
124  -D BUILD_SHARED_LIBS=OFF \
125  -D USE_LIBB2=ON \
126  -D ENABLE_TRACE=ON
127 $ cmake --build build --config Release --target check
128 ```
129 
130 You can also use ccmake or cmake-gui to interactively configure and generate
131 into a separate build directory with;
132 
133 ```Shell
134 $ ccmake -B build
135 ```
136 
137 ## Coding
138 
139 The prefered style for code is equivalent to using GNU indent with the
140 following arguments;
141 
142 ```Shell
143 $ indent -linux -nut -i4 -ppi2 -l80 -lc80 -fc1 -sob -T FILE -T Rollsum -T rs_result
144 ```
145 
146 The preferred style for non-docbook comments are as follows;
147 
148 ```C
149 
150  /*=
151  | A short poem that
152  | shall never ever be
153  | reformated or reindented
154  */
155 
156  /* Single line comment indented to match code indenting. */
157 
158  /* Blank line delimited paragraph multi-line comments.
159 
160  Without leading stars, or blank line comment delimiters. */
161 
162  int a; /* code line comments */
163 ```
164 
165 The preferred style for docbook comments is javadoc with autobrief as
166 follows;
167 
168 ```C
169 /** /file file.c
170  * Brief summary paragraph.
171  *
172  * With blank line paragraph delimiters and leading stars.
173  *
174  * /param foo parameter descriptions...
175  *
176  * /param bar ...in separate blank-line delimited paragraphs.
177  *
178  * Example:/code
179  * code blocks that will never be reformated.
180  * /endcode
181  *
182  * Without blank-line comment delimiters. */
183 
184  int a; /**< brief attribute description */
185  int b; /**< multiline attribute description
186  *
187  * With blank line delimited paragraphs.*/
188 ```
189 
190 There is a `make tidy` target that will use GNU indent to reformat all code
191 and non-docbook comments, doing some pre/post processing with sed to handle
192 some corner cases indent doesn't handle well.
193 
194 There is a `make tidyc` target that will reformat all code and comments with
195 [tidyc](https://github.com/dbaarda/tidyc). This will also correctly reformat
196 all docbook comments, equivalent to running tidyc with the following
197 arguments;
198 
199 ```Shell
200 $ tidyc -R -C -l80 -T FILE -T Rollsum -T rs_result
201 ```
202 
203 There is `make clang-tidy` and `make iwyu` targets for checking for coding
204 errors and incorrect `#include` statements. Note that the iwyu check gets
205 confused by and will emit warnings about `fileutil.c` which has extra
206 conditional includes necessary to find working functions on various platforms.
207 Other than `fileutil.c` both checks should be clean.
208 
209 If iwyu finds problems, `make ifwu-fix` can be run to automatically fix them,
210 followed by `make tidyc` to reformat the result to our preferred style. Note
211 that this doesn't always produce an ideal result and may require manual
212 intervention.
213 
214 Please try to update docs and tests in parallel with code changes.
215 
216 ## Testing
217 
218 Using `make check` will compile and run all tests. Additional code correctness
219 checks can be run with `make clang-tidy` and `make iwyu`.
220 
221 Note that `assert()` is used extensively within the code for verifying the
222 correctness of internal operations using a roughly design-by-contract
223 approach. These are only enabled for Debug builds, so testing with a Debug
224 build will give a better chance of identifying problems during development.
225 Once you are confident the code is correct, a Release build will turn these
226 off giving faster execution.
227 
228 There are also GitHub Actions configured for the librsync project to
229 configure, build, test, and lint everything on a variety of different
230 platforms with a variety of different settings. These are run against any pull
231 request or commit, and are a good way to check things are not broken for other
232 platforms.
233 
234 Test results for builds of public github branches are at
235 https://github.com/librsync/librsync/actions.
236 
237 ## Documenting
238 
239 [NEWS.md](NEWS.md) contains a list of user-visible changes in the library
240 between release versions. This includes changes to the way it's packaged, bug
241 fixes, portability notes, changes to the API, and so on. Add and update items
242 under a "Changes in X.Y.Z" heading at the top of the file. Do this as you go
243 along, so that we don't need to work out what happened when it's time for a
244 release.
245 
246 [TODO.md](TODO.md) contains a list of ideas and proposals for the future.
247 Ideally entries should be formated in a way that can be just moved into
248 [NEWS.md](NEWS.md) when they are done. Regularly check to see if there is
249 anything that needs removing or updating.
250 
251 ## Submitting
252 
253 Fixes or improvements in pull requests are welcome. Please:
254 
255 - [ ] Send small PRs that address one issues each.
256 
257 - [ ] Update `NEWS.md` to say what you changed.
258 
259 - [ ] Add a test as a self-contained C file in `tests/` that passes or fails,
260  and is hooked into `CMakeLists.txt`.
261 
262 - [ ] Keep the code style consistent with what's already there, especially in
263  keeping symbols with an `rs_` prefix.
264 
265 ## Releasing
266 
267 If you are making a new tarball release of librsync, follow this checklist:
268 
269 * Make a "Release vx.x.x" pull request containing updates ready for the
270  release including;
271 
272  * Review the changes included and decide if the release should be a major
273  (non-backwards compatible change), minor (backwards compatible change),
274  or micro (bugfix only change) version number change to get the new
275  "X.Y.Z" version number.
276 
277  * NEWS.md - make sure the top "Changes in X.Y.Z" is correct, and the date
278  is correct. Make sure the changes since the last release are documented.
279 
280  * TODO.md - check if anything needs to be removed or updated.
281 
282  * `CMakeLists.txt` - version is correct.
283 
284  * `librsync.spec` - make sure version and URL are right.
285 
286 * Run `make all doc check` in a clean checkout of the release pull request
287  branch. Also check the GitHub Actions [check and lint
288  status](https://github.com/librsync/librsync/actions) of the last commit on
289  github. If it all looks good merge the release pull request on github.
290 
291 * Draft a new release on github, typing in the release details including an
292  overview, included changes, and known issues. The overview should give an
293  indication of the magnitude of the changes and their impact, and the
294  relative urgency to upgrade. The included changes should come from the
295  NEWS.md for the release. It's probably easiest to copy and edit the previous
296  release.
297 
298 * After creating the release, download the `Source code (tar.gz)` release
299  asset. Go to "Actions", find the workflow run for the "Check" corresponding
300  to the merge of the release pull request, and download the `install results
301  windows-latest Release` artifact renamed to `librsync-win64-X.Y.Z.zip`. Edit
302  the release, and upload the source code and windows artifacts. This ensures
303  that the release includes a stable tarball (See
304  https://github.com/librsync/librsync/issues/146 for details) and win64
305  install.
306 
307 * Run `make doc` on a clean checkout of the new release tag and `cp -av html/*`
308  into a `rm -Rf *` emptied checkout of librsync.github.io and check it in.
309  This ensures it includes deletes of obsolete files as well as new and
310  updated files. Push this to update the online docs.
311 
312 * Create and merge a "Prepare vX.Y.Z+1." pull request containing updates to
313  prepare for the changes in the next release including;
314 
315  * Bump the minor version in `CMakeLists.txt`.
316 
317  * Add a `NOT RELEASED YET` version entry in `NEWS.md`
318 
319  * Bump the minor version and add a `%changelog` entry in `librsync.spec`.