Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / df6ff9608993af974b7be787dcf63bbb958e82be / . / org.jacoco.doc / docroot / doc / conventions.html
blob: 4f983c8d3dfc019324e1d40cb06ada739e8d1c08 [file] [log] [blame]
Marc R. Hoffmannadc97d92009-10-16 08:24:59 +0000[diff] [blame]1<?xml version="1.0" encoding="ISO-8859-1" ?>
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=ISO-8859-1" />
6 <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
7 <title>JaCoCo - Development Conventions</title>
8</head>
9<body>
10
11<div class="breadcrumb">
12 <a href="../index.html" class="el_session">JaCoCo</a> &gt;
13 <a href="index.html" class="el_group">Documentation</a> &gt;
14 <span class="el_source">Development Conventions</span>
15</div>
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]16<div id="content">
Marc R. Hoffmannadc97d92009-10-16 08:24:59 +0000[diff] [blame]17
18<h1>Development Conventions</h1>
19
20<p>
21 Efficient team work that produces high-quality software requires a common set
22 of rules.
23</p>
24
Marc R. Hoffmann14599742010-03-09 16:34:13 +0000[diff] [blame]25<h2>Consistent Source Tree</h2>
Marc R. Hoffmannadc97d92009-10-16 08:24:59 +0000[diff] [blame]26
27<p>
28 Update your sources and run the build locally before every check-in. Commit
29 only if the build succeeds.
30</p>
31
32<p>
33 Documentation is part of the product. Whenever you implement a new feature or
34 change existing behavior make sure to update all corresponding JavaDoc as well
35 as other documentation with the same change set. The product should always be
Marc R. Hoffmann5737e622010-01-26 20:03:52 +0000[diff] [blame]36 in a consistent state. For every change the following items should be checked:
Marc R. Hoffmannadc97d92009-10-16 08:24:59 +0000[diff] [blame]37</p>
38
Marc R. Hoffmann5737e622010-01-26 20:03:52 +0000[diff] [blame]39<ul>
40 <li>Corresponding JavaDoc.</li>
41 <li>Documentation referring to the modified concepts, interfaces or
42 implementation.</li>
43 <li>New features, bug fixes and modified behavior should be enlisted in the
44 <code>org.jacoco.doc/docroot/doc/changes.html</code> file together with
45 the corresponding issue tracker id.</li>
46</ul>
47
Marc R. Hoffmann14599742010-03-09 16:34:13 +0000[diff] [blame]48<h2>Design for Integration</h2>
49
50<p>
51 The primary focus of the JaCoCo project is to provide a code coverage library.
52 Integrators may want to embed JaCoCo in different tools and environments with
53 very different usage scenarios. Therefore following aspects should be considered:
54</p>
55
56<p>
57 <b>Documentation:</b> All APIs should be properly documented on different
58 levels of granularity:
59</p>
60
61<ul>
62 <li>General usage</li>
63 <li>Bundle summary</li>
64 <li>Package summary</li>
65 <li>Type description</li>
66 <li>Member description</li>
67</ul>
68
69<p>
70 <b>Proper Units:</b> All APIs and internal implementation classes should form proper
71 units with well defined responsibilities and dependencies. Each class and method
72 should focus on a single concept. It should be possible to use different aspects
73 separately.
74</p>
75
76<p>
77 <b>Abstraction:</b> All APIs must use the most general abstractions possible. For instance
78 reading binary data should rely on the <code>java.io.InputStream</code> interface, not
79 on a <code>java.io.File</code> object.
80</p>
81
82<p>
83 <b>System Dependencies:</b> Avoid any dependencies to the local file system, network
84 resources, threads, processes etc.
85</p>
86
87<h2>Test Driven Development</h2>
88
89<p>
90 All code added to JaCoCo should have corresponding JUnit test cases. Ideally tests
91 are developed before or along with the actual implementation:
92</p>
93
94<ul>
95 <li>Every new feature should be verified by test cases.</li>
96 <li>Modified behavior should also be reflected by test cases.</li>
97 <li>Ideally for every reported bug a reproducer is added to the unit tests.</li>
98</ul>
99
100<h2>Keep an Eye on License Issues</h2>
Marc R. Hoffmannadc97d92009-10-16 08:24:59 +0000[diff] [blame]101
102<p>
103 All code included with JaCoCo must conform to the EPL license.
104</p>
105
106<ul>
Marc R. Hoffmann5737e622010-01-26 20:03:52 +0000[diff] [blame]107 <li>
108 Every committer and contributor must agree that all code will be published
109 under EPL. He or she must be the original author and must have the
110 permission to contribute code to JaCoCo, for example if such a permission
111 is required by the employer.
112 </li>
113 <li>
114 Every third party content must be enlisted in the corresponding
115 <code>about.html</code> file along with its license.
116 </li>
117 <li>
118 Every third party content included with the JaCoCo distribution must be
119 enlisted in the <code>org.jacoco.doc/docroot/doc/license.html</code> file
120 and the corresponding <code>about.html</code> file along with its license.
121 </li>
122 <li>
123 Every source file (Java, Build Script, DTD) must have a
124 <a href="http://www.eclipse.org/legal/copyrightandlicensenotice.php">EPL
125 license notice</a>. The initial contributor should be listed. In case of
126 significant changes or additions additional contributors should also
127 be listed.
Marc R. Hoffmannadc97d92009-10-16 08:24:59 +0000[diff] [blame]128 </li>
129</ul>
130
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]131</div>
Marc R. Hoffmannadc97d92009-10-16 08:24:59 +0000[diff] [blame]132<div class="footer">
Marc R. Hoffmanndf6ff962010-04-09 15:31:22 +0000[diff] [blame^]133 <div class="versioninfo"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</div>
134 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
Marc R. Hoffmannadc97d92009-10-16 08:24:59 +0000[diff] [blame]135</div>
136
137</body>
138</html>