1*7e63c127SSorin Basca<?xml version="1.0" encoding="UTF-8" ?> 2*7e63c127SSorin Basca<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3*7e63c127SSorin Basca<html xmlns="http://www.w3.org/1999/xhtml" lang="en"> 4*7e63c127SSorin Basca<head> 5*7e63c127SSorin Basca <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6*7e63c127SSorin Basca <link rel="stylesheet" href="resources/doc.css" charset="UTF-8" type="text/css" /> 7*7e63c127SSorin Basca <link rel="shortcut icon" href="resources/report.gif" type="image/gif" /> 8*7e63c127SSorin Basca <title>JaCoCo - Development Conventions</title> 9*7e63c127SSorin Basca</head> 10*7e63c127SSorin Basca<body> 11*7e63c127SSorin Basca 12*7e63c127SSorin Basca<div class="breadcrumb"> 13*7e63c127SSorin Basca <a href="../index.html" class="el_report">JaCoCo</a> > 14*7e63c127SSorin Basca <a href="index.html" class="el_group">Documentation</a> > 15*7e63c127SSorin Basca <span class="el_source">Development Conventions</span> 16*7e63c127SSorin Basca</div> 17*7e63c127SSorin Basca<div id="content"> 18*7e63c127SSorin Basca 19*7e63c127SSorin Basca<h1>Development Conventions</h1> 20*7e63c127SSorin Basca 21*7e63c127SSorin Basca<p> 22*7e63c127SSorin Basca Efficient team work that produces high-quality software requires a common set 23*7e63c127SSorin Basca of rules. 24*7e63c127SSorin Basca</p> 25*7e63c127SSorin Basca 26*7e63c127SSorin Basca<h2>Consistent Source Tree</h2> 27*7e63c127SSorin Basca 28*7e63c127SSorin Basca<p> 29*7e63c127SSorin Basca Follow the existing coding style and formatting rules. The projects contain 30*7e63c127SSorin Basca auto-formatting rules for the Eclipse IDE. 31*7e63c127SSorin Basca</p> 32*7e63c127SSorin Basca 33*7e63c127SSorin Basca<p> 34*7e63c127SSorin Basca Update your local branches and run the build locally before every push. Push 35*7e63c127SSorin Basca only if the build succeeds and the configured compiler settings do not show 36*7e63c127SSorin Basca any warnings in the Eclipse IDE. 37*7e63c127SSorin Basca</p> 38*7e63c127SSorin Basca 39*7e63c127SSorin Basca<p> 40*7e63c127SSorin Basca Documentation is part of the product. Whenever you implement a new feature or 41*7e63c127SSorin Basca change existing behavior make sure to update all corresponding JavaDoc as well 42*7e63c127SSorin Basca as other documentation with the same change set. The product should always be 43*7e63c127SSorin Basca in a consistent state. For every change the following items should be checked: 44*7e63c127SSorin Basca</p> 45*7e63c127SSorin Basca 46*7e63c127SSorin Basca<ul> 47*7e63c127SSorin Basca <li>Corresponding JavaDoc, every public type and member requires JavaDoc.</li> 48*7e63c127SSorin Basca <li>Documentation referring to the modified concepts, interfaces or 49*7e63c127SSorin Basca implementation.</li> 50*7e63c127SSorin Basca <li>New features, bug fixes and modified behavior should be enlisted in the 51*7e63c127SSorin Basca <code>org.jacoco.doc/docroot/doc/changes.html</code> file together with 52*7e63c127SSorin Basca the corresponding issue tracker id.</li> 53*7e63c127SSorin Basca</ul> 54*7e63c127SSorin Basca 55*7e63c127SSorin Basca<h2>Design for Integration</h2> 56*7e63c127SSorin Basca 57*7e63c127SSorin Basca<p> 58*7e63c127SSorin Basca The primary focus of the JaCoCo project is to provide a code coverage library. 59*7e63c127SSorin Basca Integrators may want to embed JaCoCo in different tools and environments with 60*7e63c127SSorin Basca very different usage scenarios. Therefore following aspects should be considered: 61*7e63c127SSorin Basca</p> 62*7e63c127SSorin Basca 63*7e63c127SSorin Basca<p> 64*7e63c127SSorin Basca <b>Documentation:</b> All APIs should be properly documented on different 65*7e63c127SSorin Basca levels of granularity: 66*7e63c127SSorin Basca</p> 67*7e63c127SSorin Basca 68*7e63c127SSorin Basca<ul> 69*7e63c127SSorin Basca <li>General usage</li> 70*7e63c127SSorin Basca <li>Bundle summary</li> 71*7e63c127SSorin Basca <li>Package summary</li> 72*7e63c127SSorin Basca <li>Type description</li> 73*7e63c127SSorin Basca <li>Member description</li> 74*7e63c127SSorin Basca</ul> 75*7e63c127SSorin Basca 76*7e63c127SSorin Basca<p> 77*7e63c127SSorin Basca <b>Proper Units:</b> All APIs and internal implementation classes should form proper 78*7e63c127SSorin Basca units with well defined responsibilities and dependencies. Each class and method 79*7e63c127SSorin Basca should focus on a single concept. It should be possible to use different aspects 80*7e63c127SSorin Basca separately. 81*7e63c127SSorin Basca</p> 82*7e63c127SSorin Basca 83*7e63c127SSorin Basca<p> 84*7e63c127SSorin Basca <b>Abstraction:</b> All APIs must use the most general abstractions possible. For instance 85*7e63c127SSorin Basca reading binary data should rely on the <code>java.io.InputStream</code> interface, not 86*7e63c127SSorin Basca on a <code>java.io.File</code> object. 87*7e63c127SSorin Basca</p> 88*7e63c127SSorin Basca 89*7e63c127SSorin Basca<p> 90*7e63c127SSorin Basca <b>System Dependencies:</b> Avoid any dependencies to the local file system, network 91*7e63c127SSorin Basca resources, threads, processes etc. 92*7e63c127SSorin Basca</p> 93*7e63c127SSorin Basca 94*7e63c127SSorin Basca<h2>Test Driven Development</h2> 95*7e63c127SSorin Basca 96*7e63c127SSorin Basca<p> 97*7e63c127SSorin Basca All code added to JaCoCo should have corresponding JUnit test cases. Ideally tests 98*7e63c127SSorin Basca are developed before or along with the actual implementation: 99*7e63c127SSorin Basca</p> 100*7e63c127SSorin Basca 101*7e63c127SSorin Basca<ul> 102*7e63c127SSorin Basca <li>Every new feature should be verified by test cases.</li> 103*7e63c127SSorin Basca <li>Modified behavior should also be reflected by test cases.</li> 104*7e63c127SSorin Basca <li>Ideally for every reported bug a reproducer is added to the unit tests.</li> 105*7e63c127SSorin Basca</ul> 106*7e63c127SSorin Basca 107*7e63c127SSorin Basca<h2>Keep an Eye on License Issues</h2> 108*7e63c127SSorin Basca 109*7e63c127SSorin Basca<p> 110*7e63c127SSorin Basca All code included with JaCoCo must conform to the EPL license. 111*7e63c127SSorin Basca</p> 112*7e63c127SSorin Basca 113*7e63c127SSorin Basca<ul> 114*7e63c127SSorin Basca <li> 115*7e63c127SSorin Basca Every committer and contributor must agree that all code will be published 116*7e63c127SSorin Basca under EPL. He or she must be the original author and must have the 117*7e63c127SSorin Basca permission to contribute code to JaCoCo, for example if such a permission 118*7e63c127SSorin Basca is required by the employer. 119*7e63c127SSorin Basca </li> 120*7e63c127SSorin Basca <li> 121*7e63c127SSorin Basca Every third party content must be enlisted in the corresponding 122*7e63c127SSorin Basca <code>about.html</code> file along with its license. 123*7e63c127SSorin Basca </li> 124*7e63c127SSorin Basca <li> 125*7e63c127SSorin Basca Every third party content included with the JaCoCo distribution must be 126*7e63c127SSorin Basca enlisted in the <code>org.jacoco.doc/docroot/doc/license.html</code> file 127*7e63c127SSorin Basca and the corresponding <code>about.html</code> file along with its license. 128*7e63c127SSorin Basca </li> 129*7e63c127SSorin Basca <li> 130*7e63c127SSorin Basca Every source file (Java, Build Script, DTD) must have a 131*7e63c127SSorin Basca <a href="http://www.eclipse.org/legal/copyrightandlicensenotice.php">EPL 132*7e63c127SSorin Basca license notice</a>. The initial contributor should be listed. In case of 133*7e63c127SSorin Basca significant changes or additions additional contributors should also 134*7e63c127SSorin Basca be listed. 135*7e63c127SSorin Basca </li> 136*7e63c127SSorin Basca</ul> 137*7e63c127SSorin Basca 138*7e63c127SSorin Basca<h2>Contribution process</h2> 139*7e63c127SSorin Basca 140*7e63c127SSorin Basca<p> 141*7e63c127SSorin Basca All changes on the JaCoCo code base are handled via 142*7e63c127SSorin Basca <a href="https://github.com/jacoco/jacoco/pulls">GitHub pull requests</a> and 143*7e63c127SSorin Basca always reviewed by a second developer. This applies for external contributors 144*7e63c127SSorin Basca as well as for project members. Beside functional correctness every pull 145*7e63c127SSorin Basca request needs to fulfill the conventions above. 146*7e63c127SSorin Basca</p> 147*7e63c127SSorin Basca 148*7e63c127SSorin Basca<p> 149*7e63c127SSorin Basca For external contributors the following recommendations will help the project 150*7e63c127SSorin Basca to incorporate their precious work: 151*7e63c127SSorin Basca</p> 152*7e63c127SSorin Basca 153*7e63c127SSorin Basca<ul> 154*7e63c127SSorin Basca <li> 155*7e63c127SSorin Basca <b>Get in touch</b>: Before you start a bigger contribution 156*7e63c127SSorin Basca please get in touch through our <a href="support.html">mailing list</a> to 157*7e63c127SSorin Basca make sure the JaCoCo project considers this in scope and the approach fits 158*7e63c127SSorin Basca in the overall architecture. 159*7e63c127SSorin Basca </li> 160*7e63c127SSorin Basca <li> 161*7e63c127SSorin Basca <b>Clear scope</b>: We track and review every semantical change through a 162*7e63c127SSorin Basca separate pull request. Pull requests handling various topics ("I fixed this 163*7e63c127SSorin Basca and that") are typically difficult in handling and are therefore declined. 164*7e63c127SSorin Basca </li> 165*7e63c127SSorin Basca <li> 166*7e63c127SSorin Basca <b>No technical debt</b>: We are committed to maintain JaCoCo in the long 167*7e63c127SSorin Basca run with on a high quality level. Therefore we will not accept contributions 168*7e63c127SSorin Basca as long as they add technical debt to the project (e.g. lack of tests or 169*7e63c127SSorin Basca design issues). 170*7e63c127SSorin Basca </li> 171*7e63c127SSorin Basca</ul> 172*7e63c127SSorin Basca 173*7e63c127SSorin Basca</div> 174*7e63c127SSorin Basca<div class="footer"> 175*7e63c127SSorin Basca <span class="right"><a href="${jacoco.home.url}">JaCoCo</a> ${qualified.bundle.version}</span> 176*7e63c127SSorin Basca <a href="license.html">Copyright</a> © ${copyright.years} Mountainminds GmbH & Co. KG and Contributors 177*7e63c127SSorin Basca</div> 178*7e63c127SSorin Basca 179*7e63c127SSorin Basca</body> 180*7e63c127SSorin Basca</html> 181
