librsync  2.3.1
CONTRIBUTING.md
1 # Contributing to librsync {#page_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 ## Code Style
7 
8 The prefered style for code is equivalent to using GNU indent with the
9 following arguments;
10 
11 ```Shell
12 $ indent -linux -nut -i4 -ppi2 -l80 -lc80 -fc1 -fca -sob
13 ```
14 
15 The preferred style for non-docbook comments are as follows;
16 
17 ```C
18 
19  /*=
20  | A short poem that
21  | shall never ever be
22  | reformated or reindented
23  */
24 
25  /* Single line comment indented to match code indenting. */
26 
27  /* Blank line delimited paragraph multi-line comments.
28 
29  Without leading stars, or blank line comment delimiters. */
30 
31  int a; /* code line comments */
32 ```
33 
34 The preferred style for docbook comments is javadoc with autobrief as
35 follows;
36 
37 ```C
38 /** /file file.c
39  * Brief summary paragraph.
40  *
41  * With blank line paragraph delimiters and leading stars.
42  *
43  * /param foo parameter descriptions...
44  *
45  * /param bar ...in separate blank-line delimited paragraphs.
46  *
47  * Example:/code
48  * code blocks that will never be reformated.
49  * /endcode
50  *
51  * Without blank-line comment delimiters. */
52 
53  int a; /**< brief attribute description */
54  int b; /**< multiline attribute description
55  *
56  * With blank line delimited paragraphs.*/
57 ```
58 
59 There is a `make tidy` target that will use GNU indent to reformat all
60 code and non-docbook comments, doing some pre/post processing with sed
61 to handle some corner cases indent doesn't handle well.
62 
63 There is also a `make tidyc` target that will reformat all code and
64 comments with https://github.com/dbaarda/tidyc. This will also
65 correctly reformat all docbook comments, equivalent to running tidyc
66 with the following arguments;
67 
68 ```Shell
69 $ tidyc -R -C -l80
70 ```
71 
72 ## Pull requests
73 
74 Fixes or improvements in pull requests are welcome. Please:
75 
76 - [ ] Send small PRs that address one issues each.
77 
78 - [ ] Update `NEWS.md` to say what you changed.
79 
80 - [ ] Add a test as a self-contained C file in `tests/` that passes or fails,
81  and is hooked into `CMakeLists.txt`.
82 
83 - [ ] Keep the code style consistent with what's already there, especially in
84  keeping symbols with an `rs_` prefix.
85 
86 
87 ## NEWS
88 
89 [NEWS.md](NEWS.md) contains a list of user-visible changes in the library between
90 releases version. This includes changes to the way it's packaged,
91 bug fixes, portability notes, changes to the API, and so on.
92 
93 Add
94 and update items under a "Changes in X.Y.Z" heading at the top of
95 the file. Do this as you go along, so that we don't need to work
96 out what happened when it's time for a release.
97 
98 ## Tests
99 
100 Please try to update docs and tests in parallel with code changes.
101 
102 ## Releasing
103 
104 If you are making a new tarball release of librsync, follow this checklist:
105 
106 * NEWS.md - make sure the top "Changes in X.Y.Z" is correct, and the date is
107  correct. Make sure the changes since the last release are documented.
108 
109 * `CMakeLists.txt` - version is correct.
110 
111 * `librsync.spec` - make sure version and URL are right.
112 
113 * Run `make all doc check` in a clean checkout of the release tag. Also check
114  the travis-cl check status of the last commit on github.
115 
116 * Draft a new release on github, typing in the release details including an
117  overview, included changes, and known issues. The overview should give an
118  indication of the magnitude of the changes and their impact, and the
119  relative urgency to upgrade. The included changes should come from the
120  NEWS.md for the release. It's probably easiest to copy and edit the previous
121  release.
122 
123 * After creating the release, download the tar.gz version, edit the release,
124  and re-upload it. This ensures that the release includes a stable tarball
125  (See https://github.com/librsync/librsync/issues/146 for details).
126 
127 Test results for builds of public github branches are at
128 https://travis-ci.org/librsync/librsync.