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