Debian Codegraph @

CONTRIBUTING

raw
1 Contributing to LCOV
2 ====================
3
4 Please read this document if you would like to help improving the LTP GCOV
5 extension (LCOV). In general, all types of contributions are welcome, for
6 example:
7
8 * Fixes for code or documentation
9 * Performance and compatibility improvements
10 * Functional enhancements
11 * New and/or improved testcases
12
13 There are some rules that these contributions must follow to be acceptable for
14 inclusion:
15
16 1. The contribution must align with the project goals of LCOV.
17 2. The contribution must follow a particular format.
18 3. The contribution must be signed.
19
20 Once you have made sure that your contribution follows these rules, open a
21 pull request for the LCOV code repository [1].
22
23
24 Signing your work
25 =================
26
27 All contributions to LCOV must be signed by putting the following line at the
28 end of the explanation of a patch:
29
30 Signed-off-by: Your Name <[email protected]>
31
32 By signing a patch, you certify the following:
33
34 By making a contribution to the LTP GCOV extension (LCOV) on
35 https://github.com/linux-test-project/lcov, I certify that:
36
37 a) The contribution was created by me and I have the right to submit it
38 under the terms and conditions of the open source license
39 "GNU General Public License, version 2 or later".
40 (http://www.gnu.org/licenses/old-licenses/gpl-2.0.html).
41
42 b) The contribution is made free of any other party's intellectual property
43 claims or rights.
44
45 c) I understand and agree that this project and the contribution are public
46 and that a record of the contribution (including all personal information
47 I submit with it, including my sign-off) is maintained indefinitely and
48 may be redistributed consistent with this project or the open source
49 license(s) involved.
50
51
52 Project goals
53 =============
54
55 The goal of LCOV is to provide a set of command line tools that can be used to
56 collect, process, and visualize code coverage data in an easy-to-use way,
57 suitable for deployment in projects of a wide range of sizes - in particular,
58 deployment in automated CI/CD systems and large projects implemented using
59 multiple languages.
60 LCOV is based on existing environment-specific profiling mechanisms including,
61 but not limited to, the gcov tool that is part of the GNU Compiler Collection
62 (GCC) [2].
63
64 If you have an idea for a contribution but are unsure if it aligns with the
65 project goals, feel free to discuss the idea using the issue tracker on the
66 LCOV code repository site [1].
67
68
69 Contribution format
70 ===================
71
72 Coding style:
73 -------------
74
75 The lcov project maintainers try to adhere to a common set of code formatting
76 rules. While no one ever agrees with anyone else's choices, almost everyone
77 agrees that consistency is better than its lack.
78
79 To this end, the lcov project uses 'perltidy' [3] to format our code.
80 Perl-Tidy-20221112 has been tested and is known to work. Newer versions
81 may also work, but some older versions are known not to.
82
83 Please execute
84 make checkstyle MODE=full UPDATE=true
85 on your code and verify correctness of the reformatting (if any) before
86 submitting a pull request.
87
88 Testing:
89 --------
90
91 At minimum, please execute
92
93 $ make test
94
95 and verify that all testcases pass, then execute
96
97 $ make clean
98
99 and verify that all shrapnel has been removed - before submitting a
100 pull request.
101
102 It is highly, highly requested that PRs containing new features be
103 accompanied by tests for those features. Lack of tests may substantially
104 delay review and/or acceptance of your contribution.
105
106 It is recommended to check code coverage of your contribution.
107 The lcov project currently uses Devel::Cover to measure perl code coverage,
108 then 'perl2lcov' and 'py2lcov' and lcov to generate a coverage report:
109
110 $ make COVERAGE=1 test
111
112 and then check coverage by pointing your browser to
113 ./tests/lcov_coveragee/index.html
114
115 Note that certain version combinations of gcc, perl, and Devel::Cover
116 will crash during test execution. To work around the issue, some tests
117 ignore these errors if passed the "--keep-going" flag:
118
119 $ make COVERAGE=1 TESTCASE_ARGS=--keep-going test
120
121 Pull requests which add tests for existing features or which enhance
122 existing tests are actively encouraged.
123 The lcov maintainers are painfully aware that the code coverage of the
124 lcov test suite on the lcov code base is embarrassingly low.
125
126 Note that existing tests and/or test drivers may themselves need to be
127 modified in order to work correctly on other platforms and with other
128 toolchains. Pull requests which address issues of this nature are
129 also actively encouraged.
130
131 Submitting a change:
132 --------------------
133
134 To contribute a change, please create a patch using 'git format-patch'.
135 Alternatively you can use the diff utility with the following command line
136 options:
137
138 diff -Naurp
139
140 Please base your changes on the most current version of LCOV. You can use the
141 following command line to obtain this version from the lcov Git repository:
142
143 git clone https://github.com/linux-test-project/lcov.git
144
145 Add a meaningful description of the contribution to the top of the patch. The
146 description should follow this format:
147
148 component: short description
149
150 detailed description
151
152 Signed-off-by: Your Name <[email protected]>
153
154 With your Signed-off-by, you certify the rules stated in section
155 "Signing your work".
156
157
158 --
159
160 [1] https://github.com/linux-test-project/lcov
161 [2] https://gcc.gnu.org
162 [3] https://metacpan.org/dist/Perl-Tidy/view/bin/perltidy