| 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 |