Gitiles
Code Review Sign In
asterix-gerrit.ics.uci.edu / incubator-asterixdb-site / e9aae954f4fbc9d655c132a0f7e8c883487f9e29 / . / content / dev-setup.html
blob: d709e3b90410b89f6fac463aaedfe57286c4bcf6 [file] [log] [blame]
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]1<!DOCTYPE html>
2<html lang="en">
3 <head>
4 <meta charset="utf-8">
5 <meta http-equiv="X-UA-Compatible" content="IE=edge">
6 <meta name="viewport" content="width=device-width, initial-scale=1">
7 <!-- The above 3 meta tags *must* come first in the head; any other head content must come *after* these tags -->
8 <meta name="description" content="">
9 <meta name="author" content="">
Ian Maxonf84cb812015-12-07 15:09:45 -0800[diff] [blame]10 <link rel="icon" href="favicon.ico">
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]11
12 <title>Contributing to AsterixDB</title>
13
14 <!-- Bootstrap core CSS -->
Ian Maxonf84cb812015-12-07 15:09:45 -0800[diff] [blame]15 <link href="css/bootstrap.min.css" rel="stylesheet">
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]16 <!-- Bootstrap theme -->
17
18 <!-- Custom styles for this template -->
Ian Maxonf84cb812015-12-07 15:09:45 -0800[diff] [blame]19 <link href="css/theme.css" rel="stylesheet">
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]20
21 <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries -->
22 <!--[if lt IE 9]>
23 <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
24 <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
25 <![endif]-->
26 <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">
27 </head>
28
29 <div class="container theme-showcase" role="main">
Till Westmann00f9bf22016-03-14 13:59:27 -0700[diff] [blame]30 <div class="masthead">
31 <p class="lead">
32 <a href="index.html">
33 <img src="img/asterixdb_tm.png" style="height:75px; width:auto; vertical-align:bottom; margin-top:10px;"/>
34 </a>
35 </p>
36 </div>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]37
Till Westmann00f9bf22016-03-14 13:59:27 -0700[diff] [blame]38 <nav class="navbar navbar-default">
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]39 <div class="container">
40 <div class="navbar-header">
41 <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target=".navbar-collapse">
42 <span class="sr-only">Toggle navigation</span>
43 <span class="icon-bar"></span>
44 <span class="icon-bar"></span>
45 <span class="icon-bar"></span>
46 </button>
Ian Maxonf84cb812015-12-07 15:09:45 -0800[diff] [blame]47 <a class="navbar-brand" href="index.html">Overview</a>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]48 </div>
49 <div class="navbar-collapse collapse">
50 <ul class="nav navbar-nav">
Ian Maxonf84cb812015-12-07 15:09:45 -0800[diff] [blame]51 <li><a href="download.html">Download</a></li>
Ian Maxona9643c82015-09-01 11:15:57 -1000[diff] [blame]52 <li class="dropdown">
53 <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Documentation<span class="caret"></span></a>
54 <ul class="dropdown-menu" role="menu">
55 <li class="dropdown-header">Stable release</li>
Ian Maxonbf2c56b2017-01-24 14:14:49 -0800[diff] [blame]56 <li><a href="docs/0.9.0/index.html">Documentation for 0.9.0<i class="fa fa-external-link fa-sm"></i></a></li>
Ian Maxona9643c82015-09-01 11:15:57 -1000[diff] [blame]57 <li class="divider"></li>
58 <li class="dropdown-header">Snapshot release</li>
Ian Maxonbf2c56b2017-01-24 14:14:49 -0800[diff] [blame]59 <li><a href="https://ci.apache.org/projects/asterixdb/index.html">Documentation for 0.9.1-SNAPSHOT <i class="fa fa-external-link fa-sm"></i></a></li>
Ian Maxona9643c82015-09-01 11:15:57 -1000[diff] [blame]60 </ul>
61 </li>
Ian Maxonf84cb812015-12-07 15:09:45 -0800[diff] [blame]62 <li><a href="about.html">About</a></li>
Till Westmann2a321022016-04-08 08:18:14 -0700[diff] [blame]63 <li class="dropdown">
64 <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Community<span class="caret"></span></a>
65 <ul class="dropdown-menu" role="menu">
66 <li><a href="community.html">Mailing Lists</a></li>
67 <li><a href="community.html#irc">IRC</a></li>
68 <li><a href="community.html#asterixdb-team">Team</a></li>
69 <li><a href="https://issues.apache.org/jira/browse/ASTERIXDB">Issue Tracker</a></li>
70 </ul>
71 </li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]72 <li class="dropdown">
Michael Blowf93d7f52016-10-07 14:36:30 -0400[diff] [blame]73 <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Development<span class="caret"></span></a>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]74 <ul class="dropdown-menu" role="menu">
75 <li class="dropdown-header">For New Contributors</li>
Ian Maxonf84cb812015-12-07 15:09:45 -0800[diff] [blame]76 <li><a href="dev-setup.html">Development Setup</a></li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]77 <li class="divider"></li>
78 <li class="dropdown-header">For Committers</li>
Ian Maxonf84cb812015-12-07 15:09:45 -0800[diff] [blame]79 <li><a href="pushing.html">Pushing changes</a></li>
80 <li><a href="site.html">Editing this site</a></li>
Michael Blowf93d7f52016-10-07 14:36:30 -0400[diff] [blame]81 <li class="dropdown-header">Extensions</li>
82 <li><a href="extension.html">Extending AsterixDB</a></li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]83 </ul>
84 </li>
85 </ul>
Till Westmann00f9bf22016-03-14 13:59:27 -0700[diff] [blame]86 <ul class="nav navbar-nav navbar-right">
87 <li class="dropdown">
88 <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false"
89 style="padding-right: 30px">
90 <img src="img/feather.png" style="height:20px"/>Apache Software Foundation<span class="caret"/>
91 </a>
92 <ul class="dropdown-menu dropdown-menu-right" role="menu">
93 <li><a href="http://www.apache.org/"><b>ASF Homepage</b></a></li>
94 <li><a href="http://www.apache.org/licenses/">License</a></li>
95 <li><a href="http://www.apache.org/foundation/sponsorship.html">Donate</a></li>
96 <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
97 <li><a href="http://www.apache.org/security/">Security</a></li>
98 </ul>
99 </li>
100 </ul>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]101 </div><!--/.nav-collapse -->
102 </div>
103 </nav>
104
105
Till Westmann00f9bf22016-03-14 13:59:27 -0700[diff] [blame]106 <div class="row">
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]107<div class="col-md-8 col-centered">
108<h2>Contributing to AsterixDB</h2>
109<hr />
110
111<ul id="markdown-toc">
112 <li><a href="#introduction" id="markdown-toc-introduction">Introduction</a></li>
Ian Maxonacb58492015-10-16 19:12:28 -0700[diff] [blame]113 <li><a href="#master-snapshots" id="markdown-toc-master-snapshots">Master snapshots</a> <ul>
Till Westmanne9aae952017-02-10 22:57:46 -0800[diff] [blame^]114 <li><a href="#server-package" id="markdown-toc-server-package">Server Package</a></li>
Ian Maxonacb58492015-10-16 19:12:28 -0700[diff] [blame]115 <li><a href="#managix-installer" id="markdown-toc-managix-installer">Managix Installer</a></li>
116 <li><a href="#yarn-installer" id="markdown-toc-yarn-installer">YARN Installer</a></li>
117 </ul>
118 </li>
Ian Maxon7bb6ace2016-07-19 11:53:43 -0700[diff] [blame]119 <li><a href="#setting-up-an-asterix-development-environment" id="markdown-toc-setting-up-an-asterix-development-environment">Setting up an Asterix Development environment</a> <ul>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]120 <li><a href="#prerequisites" id="markdown-toc-prerequisites">Prerequisites</a></li>
121 <li><a href="#steps" id="markdown-toc-steps">Steps</a></li>
122 </ul>
123 </li>
124 <li><a href="#signing-up-for-gerrit" id="markdown-toc-signing-up-for-gerrit">Signing Up for Gerrit</a></li>
125 <li><a href="#configuring-your-local-working-environment-for-gerrit" id="markdown-toc-configuring-your-local-working-environment-for-gerrit">Configuring your local working environment for Gerrit</a> <ul>
126 <li><a href="#one-time-tasks" id="markdown-toc-one-time-tasks">One-time tasks</a></li>
127 <li><a href="#once-per-repository-tasks" id="markdown-toc-once-per-repository-tasks">Once-per-repository tasks</a></li>
128 </ul>
129 </li>
130 <li><a href="#making-changes---working-method" id="markdown-toc-making-changes---working-method">Making Changes - working method</a></li>
131 <li><a href="#making-more-changes" id="markdown-toc-making-more-changes">Making More Changes</a></li>
132 <li><a href="#using-jenkins-with-gerrit" id="markdown-toc-using-jenkins-with-gerrit">Using Jenkins with Gerrit</a> <ul>
133 <li><a href="#verification" id="markdown-toc-verification">Verification</a></li>
134 <li><a href="#retrigggering-builds-and-triggering-builds-manually" id="markdown-toc-retrigggering-builds-and-triggering-builds-manually">Retrigggering builds and triggering builds manually</a></li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]135 </ul>
136 </li>
137</ul>
138
139<hr />
140
141<h2 id="introduction">Introduction</h2>
Till Westmanndadc9b72016-04-26 17:24:34 -0700[diff] [blame]142<p>We warmly welcome any contributions to the Apache AsterixDB™ or related (Hyracks, Pregelix) projects.
Till Westmann00f9bf22016-03-14 13:59:27 -0700[diff] [blame]143A great way to start contributing is to pick a bug labelled starter in JIRA and submit a patch for it, to get acquainted with our codebase and development process.</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]144
145<hr />
146
Ian Maxonacb58492015-10-16 19:12:28 -0700[diff] [blame]147<h2 id="master-snapshots">Master snapshots</h2>
148<p>If you are a developer simply looking for a snapshot of the latest development version of AsterixDB to test out your application that is based on top of AsterixDB, snapshots from the latest successful push to our master branch are available below. These are non ASF-release, automatic builds.</p>
149
Till Westmanne9aae952017-02-10 22:57:46 -0800[diff] [blame^]150<h3 id="server-package">Server Package</h3>
151<p><a class="btn btn-md btn-warning" href="https://asterix-jenkins.ics.uci.edu/job/asterix-integration-tests/lastSuccessfulBuild/org.apache.asterix$asterix-server/artifact/org.apache.asterix/asterix-server/0.9.1-SNAPSHOT/asterix-server-0.9.1-SNAPSHOT-binary-assembly.zip" role="button">Download AsterixDB 0.9.1-SNAPSHOT <i class="fa fa-download fa-lg"></i> </a></p>
152
Ian Maxonacb58492015-10-16 19:12:28 -0700[diff] [blame]153<h3 id="managix-installer">Managix Installer</h3>
Ian Maxonbf2c56b2017-01-24 14:14:49 -0800[diff] [blame]154<p><a class="btn btn-md btn-warning" href="https://asterix-jenkins.ics.uci.edu/job/asterix-integration-tests/lastSuccessfulBuild/org.apache.asterix$asterix-installer/artifact/org.apache.asterix/asterix-installer/0.9.1-SNAPSHOT/asterix-installer-0.9.1-SNAPSHOT-binary-assembly.zip" role="button">Download AsterixDB 0.9.1-SNAPSHOT <i class="fa fa-download fa-lg"></i> </a></p>
Ian Maxonacb58492015-10-16 19:12:28 -0700[diff] [blame]155
156<h3 id="yarn-installer">YARN Installer</h3>
Ian Maxonbf2c56b2017-01-24 14:14:49 -0800[diff] [blame]157<p><a class="btn btn-md btn-warning" href="https://asterix-jenkins.ics.uci.edu/job/asterix-integration-tests/lastSuccessfulBuild/org.apache.asterix$asterix-yarn/artifact/org.apache.asterix/asterix-yarn/0.9.1-SNAPSHOT/asterix-yarn-0.9.1-SNAPSHOT-binary-assembly.zip" role="button">Download AsterixDB 0.9.1-SNAPSHOT <i class="fa fa-download fa-lg"></i> </a></p>
Ian Maxonacb58492015-10-16 19:12:28 -0700[diff] [blame]158
159<hr />
160
Ian Maxon7bb6ace2016-07-19 11:53:43 -0700[diff] [blame]161<h2 id="setting-up-an-asterix-development-environment">Setting up an Asterix Development environment</h2>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]162
163<h3 id="prerequisites">Prerequisites</h3>
164<ul>
165 <li>A suitable *nix environment (Linux, OSX)</li>
Ian Maxon1bd67772015-11-12 16:14:20 -0800[diff] [blame]166 <li>JDK 1.8+</li>
Till Westmann0cb533a2016-07-12 22:17:50 -0700[diff] [blame]167 <li>Maven 3.3.9 or greater</li>
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]168 <li>Eclipse Juno (or later) or IntelliJ IDEA 15.0 (or later)</li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]169</ul>
170
171<h3 id="steps">Steps</h3>
172
Ian Maxon7bb6ace2016-07-19 11:53:43 -0700[diff] [blame]173<h4 id="general-setup">General setup</h4>
174
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]175<ol>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]176 <li>
Taewoo Kim12b53a22016-07-08 14:02:15 -0700[diff] [blame]177 <p>Check out AsterixDB master in one folder via git in the command line. Assume that the path is <code>$HOME/workspace</code>.</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]178
Till Westmann0cb533a2016-07-12 22:17:50 -0700[diff] [blame]179 <pre><code> git clone https://github.com/apache/asterixdb/
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]180</code></pre>
181
Taewoo Kim12b53a22016-07-08 14:02:15 -0700[diff] [blame]182 <p>You will now have <code>$HOME/workspace/asterixdb/</code>.</p>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]183 </li>
184 <li>
Taewoo Kim12b53a22016-07-08 14:02:15 -0700[diff] [blame]185 <p>Go to the asterixdb folder and install it’s artifacts to the local Maven repository by executing the following commands:</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]186
Till Westmann0cb533a2016-07-12 22:17:50 -0700[diff] [blame]187 <pre><code> cd asterixdb/
188 mvn install -DskipTests
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]189</code></pre>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]190 </li>
Ian Maxon7bb6ace2016-07-19 11:53:43 -0700[diff] [blame]191</ol>
192
193<h4 id="intellij-idea-ide-setup">IntelliJ IDEA IDE Setup</h4>
194
195<ol>
196 <li>In IntelliJ IDEA, import asterixdb as an existing Maven Project.
197 <ul>
198 <li><code>File -&gt; New -&gt; Project from existing sources</code>, or `Import project…’ when on a new install</li>
199 <li>Then, select the ‘pom.xml’ in the root of the checked out git repository.</li>
200 <li>The default options for import should suffice, so just click <code>Next</code></li>
201 <li>Also click <code>Next</code> when selecting for profiles and versions</li>
202 <li>On the JDK Selection screen, be sure to select a JDK &gt; 1.8, OpenJDK or Oracle is fine.</li>
203 <li>Give IntelliJ some time to import the Maven project and its dependencies</li>
204 <li>Once everything is finished, you should see ‘asterixdb’ and ‘hyracks-fullstack’ modules in the “Project” view.</li>
205 </ul>
206 </li>
207 <li>Set up IntelliJ code formatting rules
208 <ul>
209 <li>Download files <a href="https://cwiki.apache.org/confluence/download/attachments/61322291/AsterixCodeFormatProfile.xml">AsterixCodeFormatProfile.xml</a>
210 <a href="https://cwiki.apache.org/confluence/download/attachments/61322291/AsterixCleanupFormatProfile.xml">AsterixCleanupFormatProfile.xml</a></li>
211 <li>Import profiles into IntelliJ</li>
212 <li><code>File -&gt; Settings -&gt; Editor -&gt; Code Style -&gt; Java</code></li>
213 <li>Then, click the <code>Manage...</code> button</li>
214 <li>Click <code>Import</code> and import the <code>AsterixCodeFormatProfile.xml</code> as an Eclipse XML profile.</li>
215 </ul>
216 </li>
217</ol>
218
219<h4 id="eclipse-ide-setup">Eclipse IDE Setup</h4>
220
221<ol>
Taewoo Kim12b53a22016-07-08 14:02:15 -0700[diff] [blame]222 <li>In Eclipse, import asterixdb as an existing Maven Project.
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]223 <ul>
224 <li><code>File -&gt; Import -&gt; Maven -&gt; Existing Maven Projects -&gt; Next</code></li>
Taewoo Kim12b53a22016-07-08 14:02:15 -0700[diff] [blame]225 <li>Specify the Root directory as <code>asterixdb</code> and then click Next until Finish is enabled.</li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]226 <li>If Eclipse tries to install the <code>m2e</code> (Maven To Eclipse) connector, let it do so.</li>
227 <li>There might be some plugin errors; however, that is not a big deal. Wait until the job finishes.</li>
Taewoo Kim12b53a22016-07-08 14:02:15 -0700[diff] [blame]228 <li>Then, click Finish. Restart Eclipse if asked to do so.</li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]229 </ul>
230 </li>
231 <li>Fix Eclipse’s build path to include compile-time generated sources.
232 <ul>
233 <li>Right click the project where a red X mark is shown(e.g. <code>asterix-algebra</code>. Then resolve by applying the following:
234 <ul>
235 <li>Right click asterix-algebra. Click Build Path and Configure Build Path. Click Add Folder.</li>
Taewoo Kim12b53a22016-07-08 14:02:15 -0700[diff] [blame]236 <li>Under the <code>target -&gt; generated sources</code>, check the parent folder of the <code>org</code> folder and click OK.</li>
Ian Maxon4baed872015-10-06 19:01:17 -0700[diff] [blame]237 <li>For example, if the directory structure is “target - generated-sources - javacc - org - apache …”, check the javacc directory and click OK. Then X mark will dissapear.</li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]238 </ul>
239 </li>
240 <li>Repeat this step to all projects which show a red X mark except “asterix-fuzzyjoin” and “asterix-transactions”.</li>
Taewoo Kim12b53a22016-07-08 14:02:15 -0700[diff] [blame]241 <li>It may be the case that only “asterix-algebra” and “asterix-external-data” will require these steps.</li>
242 <li>If you see “plugin execution not covered by lifecycle configuration” errors such as this one - “Plugin execution not covered by lifecycle configuration: org.apache.asterix:asterix-test-datagenerator-maven-plugin:0.8.9-SNAPSHOT:generate-testdata (execution: replace-template-data, phase: process-test-resources)”, try to resolve it using the quick fix feature. You can call this feature by right click on the error and select “quick fix”. And then choose “Mark goal generate-testdata as ignored in Eclipse build in Eclipse preferences”.</li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]243 </ul>
244 </li>
245 <li>Set up Eclipse code formatting rules
246 <ul>
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]247 <li>Download files <a href="https://cwiki.apache.org/confluence/download/attachments/61322291/AsterixCodeFormatProfile.xml">AsterixCodeFormatProfile.xml</a>
248 <a href="https://cwiki.apache.org/confluence/download/attachments/61322291/AsterixCleanupFormatProfile.xml">AsterixCleanupFormatProfile.xml</a></li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]249 <li>Import profiles into Eclipse
250 <ul>
251 <li>Preferences -&gt; Java -&gt; Code style -&gt; Formatter -&gt; Import -&gt; Select AsterixCodeFormatProfile.xml</li>
252 <li>Preferences -&gt; Java -&gt; Code style -&gt; Clean up -&gt; Import -&gt; Select AsterixCleanupFormatProfile.xml</li>
253 <li>Preferences -&gt; Java -&gt; Editor -&gt; Save actions -&gt; Perform the selected action on save -&gt; Format source code</li>
254 </ul>
255 </li>
256 </ul>
257 </li>
Taewoo Kim12b53a22016-07-08 14:02:15 -0700[diff] [blame]258 <li>
259 <p>Lastly, go to the asterixdb folder and execute following command again. This is required since Eclipse might have cleaned the projects and rebuilt the them without creating all necessary classes. Currently, some of the class files can be only built using mvn command.</p>
260
Till Westmann0cb533a2016-07-12 22:17:50 -0700[diff] [blame]261 <pre><code> cd asterixdb/
262 mvn install -DskipTests
Taewoo Kim12b53a22016-07-08 14:02:15 -0700[diff] [blame]263</code></pre>
264 </li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]265</ol>
266
267<hr />
268
269<h2 id="signing-up-for-gerrit">Signing Up for Gerrit</h2>
270
Ian Maxon4baed872015-10-06 19:01:17 -0700[diff] [blame]271<p>First, to contribute patches to AsterixDB, you should have an ICLA on file with the Apache Software Foundation.
272For details see the ASF website <a href="https://www.apache.org/dev/new-committers-guide.html#cla">here</a>
273You should only need to perform the following steps once.</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]274
275<p>Our Gerrit server is <a href="https://asterix-gerrit.ics.uci.edu/">here</a></p>
276
277<ol>
278 <li>Visit the above URL, and click on “Register” in the upper right.</li>
279 <li>Gerrit uses OpenID; you may create an account using any OpenID provider, or with a Yahoo! account.</li>
280 <li>Click on “Sign in with a Yahoo! ID”. You will be taken to a page to log in to Yahoo!.</li>
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]281 <li>From there, you will get a page asking you to allow <code>asterix-gerrit.ics.uci.edu</code> to access your email and basic information. Approve this request.</li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]282 <li>You will be directed back to Gerrit to complete the account signup. Make sure to fill out this page! It is necessary to allow you to push code changes to Gerrit for review.</li>
283 <li>For “Full Name” and “Preferred Email”, enter what you like. If you would like to register a different email address such as an @uci.edu address, you may do so. This is where Gerrit will send you notifications about code review requests, voting, and so on.</li>
284 <li>For “Select a unique username”, choose a short alphanumeric ID. This will be your ssh username for git access. Be sure to click “Select Username” to verify that the name is unique and allowed.</li>
285 <li>Also provide a ssh public key here. There is information on the page on creating one if you do not have one. Click “Add” when done.
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]286Note that you can create a new ssh public key just for Gerrit if you like; if you do so you will need to modify your <code>.ssh/config</code> file to ensure the right key is selected.</li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]287 <li>Click “Continue” at the bottom of the page.</li>
288 <li>
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]289 <p>Finally, verify that you have everything set up: From a command-line, type</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]290
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]291 <pre><code>ssh -p 29418 username@asterix-gerrit.ics.uci.edu
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]292</code></pre>
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]293 </li>
294 <li>
295 <p>You should see</p>
296
297 <pre><code>**** Welcome to Gerrit Code Review ****
298
299Hi Full Name, you have successfully connected over SSH.
300
301Unfortunately, interactive shells are disabled.
302To clone a hosted Git repository, use:
303
304git clone ssh://username@asterix-gerrit.ics.uci.edu:29418/REPOSITORY_NAME.git
305</code></pre>
306 </li>
307</ol>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]308
309<p>At this point, please send an email to Chris or Ian, specifying the email address of your new account, and ask to be added to the “AsterixDB Devs” group. You may push change proposals to Gerrit, and vote +1/-1 Code Review on any proposals without being in AsterixDB Devs, but you cannot vote +2 on anything to allow a change to be merged.</p>
310
311<hr />
312
313<h2 id="configuring-your-local-working-environment-for-gerrit">Configuring your local working environment for Gerrit</h2>
314
315<h3 id="one-time-tasks">One-time tasks</h3>
316
317<ol>
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]318 <li>
319 <p>At the command-line, run the following. Replace “username” with the user name you chose in step 7 above.</p>
320
321 <pre><code>git config --global gerrit.url ssh://username@asterix-gerrit.ics.uci.edu:29418/
322</code></pre>
323 </li>
324 <li>
325 <p>Download my “git-gerrit” utility library:</p>
326
327 <pre><code>git clone https://github.com/ceejatec/git-gerrit
328</code></pre>
329 </li>
330 <li>
331 <p>Ensure that the <code>git-gerrit/git-gerrit</code> script is on your PATH. You could copy it to somewhere, but it would be best to leave it inside the github clone so you can easily get updates.</p>
332 </li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]333</ol>
334
335<h3 id="once-per-repository-tasks">Once-per-repository tasks</h3>
336
337<ol>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]338 <li>
339 <p>To work on (say) Asterix, first clone the GitHub mirror or the ASF repository (if you already have a local clone, great!), e.g.</p>
340
Till Westmann0cb533a2016-07-12 22:17:50 -0700[diff] [blame]341 <pre><code>git clone https://github.com/apache/asterixdb
342</code></pre>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]343 </li>
344 <li>
345 <p><code>cd</code> into the clone repo directory, and then run the following command to create the “gerrit” remote.</p>
346
Till Westmann0cb533a2016-07-12 22:17:50 -0700[diff] [blame]347 <pre><code>git gerrit init
348</code></pre>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]349 </li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]350</ol>
351
352<hr />
353
354<h2 id="making-changes---working-method">Making Changes - working method</h2>
355
356<ol>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]357 <li>
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]358 <p>When you want to start working on a bug, feature, etc, first make a local <code>git</code> branch. Never work directly on
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]359 <code>master</code>! <code>master</code> should always be a pure mirror of <code>origin/master</code>, i.e., the GitHub mirror or the ASF repository.</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]360
Till Westmann0cb533a2016-07-12 22:17:50 -0700[diff] [blame]361 <pre><code>git checkout -b my_branch
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]362</code></pre>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]363 </li>
364 <li>
365 <p>Make your changes, test them, etc. Feel free to <code>git commit</code> as often as you like.</p>
366 </li>
367 <li>
368 <p><strong>Optional</strong>: If you like, you can push your branch up to another git repository (e.g. in your own GitHub account), either to share it with others or as a backup. You may do this at whatever point in time you like.</p>
369 </li>
370 <li>
371 <p>Every so often, you should update your local <code>master</code> mirror, and then merge that onto your working branch. This will prevent your branch from falling too far out of date, and ensure that your code review proposals will merge successfully with <code>master</code>. There are a number of ways to do this, but <code>git-gerrit</code> provides a convenience function:</p>
Ian Maxonf84cb812015-12-07 15:09:45 -0800[diff] [blame]372
Till Westmann0cb533a2016-07-12 22:17:50 -0700[diff] [blame]373 <pre><code>git gerrit update
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]374</code></pre>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]375 </li>
376 <li>
377 <p>When you are ready to submit changes for code review, first ensure that you have committed everything locally that is necessary (<code>git status</code> should report “nothing to commit, working directory clean”). This is also a good time to update (see step 4). Then run:</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]378
Till Westmann0cb533a2016-07-12 22:17:50 -0700[diff] [blame]379 <pre><code>git gerrit submit
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]380</code></pre>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]381 </li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]382 <li>This will pop open your editor to invite you to create a good commit message. This will be the single commit message which will be the only one to appear in the project’s master git history. Take the time to make it clear. The editor will contain the log messages of everything you committed on your branch as a reminder, but generally you will want to delete all this and replace it with a comprehensive message. Also: As noted in the initial message, the last line of the buffer will contain a <code>Change-Id</code> field. Do not delete that line! It is used by Gerrit to identify this particular merge proposal.</li>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]383 <li>
384 <p>When you save your commit message, git-gerrit will push all of the changes from your working branch up to Gerrit. Assuming no errors, you should see output similar to the following:</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]385
Till Westmann0cb533a2016-07-12 22:17:50 -0700[diff] [blame]386 <pre><code>remote: Resolving deltas: 100% (1/1)
387remote: Processing changes: new: 1, refs: 1, done
388remote:
389remote: New Changes:
390remote: http://fulliautomatix.ics.uci.edu:8443/30
391remote:
392To ssh://ceej@fulliautomatix.ics.uci.edu:29418/ceej-gerrit-test
393 * [new branch] HEAD -&gt; refs/for/master
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]394</code></pre>
Till Westmann0cf36632015-12-08 21:57:33 -0800[diff] [blame]395 </li>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]396 <li>That URL under “New Changes” is your code review! Send it to others to request reviews.</li>
397 <li>If you get any negative code reviews and need to make changes, you can just repeat steps 2 - 6 of the working method. Your local branch will still have all the history you put there, if you need to revert changes or look back and see what you did, etc.</li>
398 <li>When you repeat step 6, you will notice two things: First, git-gerrit keeps the change message for you, including the Change-Id, so you don’t have to re-invent it every time. Second, the output from <code>git gerrit submit</code> will not include the URL of the review this time. I’m not sure why; I wish it did. But if you re-visit the old URL in your browser, you should see an additional “Patch Set” containing your revised changes for people to review.</li>
399</ol>
400
401<h2 id="making-more-changes">Making More Changes</h2>
402
403<p>You may have as many feature branches as you want locally, and each may be at any point in the review cycle.</p>
404
405<p>Once you are done with a change (that is, it has been Code Reviewed and approved in Gerrit and merged), it is probably best to start work on the next big thing on a new branch. However, git-gerrit attempts to be smart if you choose to re-use a branch. For example, it should notice if the “current” Change-Id for a branch has been merged to master, and it will create a new Change-Id and a new fresh commit message the next time you run <code>git gerrit submit</code>.</p>
406
407<p>In that case, you may notice that the list of changes on the branch still contains older commits which have been merged. That is due to the unfortunate way Gerrit works; it requires squashing to a single git commit for review, which loses the association with the original commits in your history.</p>
408
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]409<p>It is also possible that you may want to re-use a branch and git-gerrit fails to notice that the older change has been merged - or perhaps the change was Abandoned on Gerrit and not merged, and you want to continue working on the same branch to create a new proposal. In this case, run</p>
410
411<pre><code>git gerrit new
412</code></pre>
413
414<p>on your branch. This will force git-gerrit to create a new Change-Id and commit message the next time you run <code>git gerrit submit</code>.</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]415
416<hr />
417
418<h2 id="using-jenkins-with-gerrit">Using Jenkins with Gerrit</h2>
419
420<h3 id="verification">Verification</h3>
421
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]422<p>As of right now, whenever a patch set is submitted to Gerrit (i.e. whenever a user performs ‘git gerrit submit’) are automatically picked up by Jenkins, which runs <code>mvn verify</code> to test the patch fully.
423Once the build finishes, Jenkins comments on the patchset and votes with the result (+1 for all tests passing, -1 for anything less).
424Ideally, and in most cases, verification of a patchset reqires no intervention.
425However there are a few exceptions to this as detailed below.</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]426
427<h3 id="retrigggering-builds-and-triggering-builds-manually">Retrigggering builds and triggering builds manually</h3>
428
429<h4 id="retriggering">Retriggering</h4>
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]430<p>Occasionally, there are builds in which tests failed, but perhaps not for a reason that has anything to do with the proposed patch’s changes.
431For example, on occasion the Integration tests can have issues with ports on the build server already being bound.
432The simple work around to this is to try building again.</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]433
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]434<p>One way to perform this is by simply visiting the link that is posted on Gerrit by Jenkins, and hitting the ‘Retrigger’ link on the left-hand side of the page.
435This will try retesting the build with the exact same parameters as last time, hopefully with a different result.</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]436
437<h4 id="manual-trigger">Manual Trigger</h4>
Till Westmannad8974b2016-07-21 18:12:01 -0700[diff] [blame]438<p>Builds of Gerrit patches can also be fully manually triggered from Jenkins.
439This can be desirable if the patch is a draft or is not triggered automatically for any other reason.
440To manually trigger a build of a patchset, visit the Jenkins front-page, and click the ‘Query and Trigger Gerrit patches’ link.
441This should link to a page allowing you to manually trigger Gerrit patches.
442In the search field any query that can be searched in the Gerrit web interface can be used, but the default query of all open patchsets is likely fine.
443Hit the ‘Search’ button, and then click the checkbox that represents the patch that needs to be built.
444Then simply click ‘Trigger Selected’ and the patch will start building.</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]445
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]446<hr />
447
448</div>
449</div>
450
451
Till Westmann00f9bf22016-03-14 13:59:27 -0700[diff] [blame]452 <hr/>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]453
Till Westmann00f9bf22016-03-14 13:59:27 -0700[diff] [blame]454 <footer>
455 <div class="row">
Till Westmann00f9bf22016-03-14 13:59:27 -0700[diff] [blame]456 <div class="col-md-9 col-centered text-center">
457 <p/>
458 <p>&copy; Copyright 2016 The Apache Software foundation. All Rights Reserved. </p>
459 <p>Apache AsterixDB, the Apache AsterixDB logo, Apache, and the Apache feather logo are trademarks of the
460 Apache Software Foundation</p>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]461 </div>
Till Westmann00f9bf22016-03-14 13:59:27 -0700[diff] [blame]462 </div>
463 </footer>
464 </div> <!-- /container -->
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]465
466 <!-- Bootstrap core JavaScript
467 ================================================== -->
468 <!-- Placed at the end of the document so the pages load faster -->
469 <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.2/jquery.min.js"></script>
Ian Maxonf84cb812015-12-07 15:09:45 -0800[diff] [blame]470 <script src="js/bootstrap.min.js"></script>
Ian Maxon3dffc852015-07-13 20:17:09 -0700[diff] [blame]471 </body>
472</html>