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