Google Git
Sign in
apache / activemq-website / e94dece0881635c464c1d5d24c3f738f86d8c4b5 / . / content / components / artemis / documentation / latest / hacking-guide / code.html
blob: dc54bae8b371521d5b9fc51acc41e80cf9a6ef3d [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="" >
<head>
<meta charset="UTF-8">
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
<title>Working with the Code ยท ActiveMQ Artemis Documentation</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="description" content="">
<meta name="generator" content="GitBook 3.2.3">
<link rel="stylesheet" href="gitbook/style.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-highlight/website.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-search/search.css">
<link rel="stylesheet" href="gitbook/gitbook-plugin-fontsettings/website.css">
<meta name="HandheldFriendly" content="true"/>
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black">
<link rel="apple-touch-icon-precomposed" sizes="152x152" href="gitbook/images/apple-touch-icon-precomposed-152.png">
<link rel="shortcut icon" href="gitbook/images/favicon.ico" type="image/x-icon">
<link rel="next" href="ide.html" />
<link rel="prev" href="notice.html" />
</head>
<body>
<div class="book">
<div class="book-summary">
<div id="book-search-input" role="search">
<input type="text" placeholder="Type to search" />
</div>
<nav role="navigation">
<ul class="summary">
<li class="chapter " data-level="1.1" data-path="./">
<a href="./">
Introduction
</a>
</li>
<li class="chapter " data-level="1.2" data-path="notice.html">
<a href="notice.html">
Legal Notice
</a>
</li>
<li class="chapter active" data-level="1.3" data-path="code.html">
<a href="code.html">
Working with the Code
</a>
</li>
<li class="chapter " data-level="1.4" data-path="ide.html">
<a href="ide.html">
IDE Integration
</a>
</li>
<li class="chapter " data-level="1.5" data-path="building.html">
<a href="building.html">
Building
</a>
</li>
<li class="chapter " data-level="1.6" data-path="tests.html">
<a href="tests.html">
Tests
</a>
</li>
<li class="chapter " data-level="1.7" data-path="code-coverage-report.html">
<a href="code-coverage-report.html">
Code coverage report
</a>
</li>
<li class="chapter " data-level="1.8" data-path="formatting.html">
<a href="formatting.html">
Code Formatting
</a>
</li>
<li class="chapter " data-level="1.9" data-path="validating-releases.html">
<a href="validating-releases.html">
Validating releases
</a>
</li>
<li class="chapter " data-level="1.10" data-path="maintainers.html">
<a href="maintainers.html">
Notes for Maintainers
</a>
</li>
<li class="chapter " data-level="1.11" data-path="history.html">
<a href="history.html">
History
</a>
</li>
<li class="divider"></li>
<li>
<a href="https://www.gitbook.com" target="blank" class="gitbook-link">
Published with GitBook
</a>
</li>
</ul>
</nav>
</div>
<div class="book-body">
<div class="body-inner">
<div class="book-header" role="navigation">
<!-- Title -->
<h1>
<i class="fa fa-circle-o-notch fa-spin"></i>
<a href="." >Working with the Code</a>
</h1>
</div>
<div class="page-wrapper" tabindex="-1" role="main">
<div class="page-inner">
<div id="book-search-results">
<div class="search-noresults">
<section class="normal markdown-section">
<h1 id="working-with-the-code">Working with the Code</h1>
<p>While the canonical Apache ActiveMQ Artemis git repository is hosted on Apache hardware at <a href="https://gitbox.apache.org/repos/asf/activemq-artemis.git" target="_blank">https://gitbox.apache.org/repos/asf/activemq-artemis.git</a>
contributors are encouraged (but not required) to use a mirror on GitHub for collaboration and pull-request review
functionality. Follow the steps below to get set up with GitHub, etc.</p>
<p>If you do not wish to use GitHub for whatever reason you can follow the overall process outlined in the &quot;Typical
development cycle&quot; section below but instead attach <a href="https://git-scm.com/docs/git-format-patch" target="_blank">a patch file</a> to the
related JIRA or an email to the <a href="http://activemq.apache.org/mailing-lists.html" target="_blank">dev list</a>.</p>
<h2 id="initial-steps">Initial Steps</h2>
<ol>
<li><p>Create a GitHub account if you don&apos;t have one already</p>
<p><a href="https://github.com" target="_blank">https://github.com</a></p>
</li>
<li><p>Fork the apache-artemis repository into your account</p>
<p><a href="https://github.com/apache/activemq-artemis" target="_blank">https://github.com/apache/activemq-artemis</a></p>
</li>
<li><p>Clone your newly forked copy onto your local workspace:</p>
<pre><code> $ git clone git@github.com:&lt;your-user-name&gt;/activemq-artemis.git
Cloning into &apos;activemq-artemis&apos;...
remote: Counting objects: 63800, done.
remote: Compressing objects: 100% (722/722), done.
remote: Total 63800 (delta 149), reused 0 (delta 0), pack-reused 62748
Receiving objects: 100% (63800/63800), 18.28 MiB | 3.16 MiB/s, done.
Resolving deltas: 100% (28800/28800), done.
Checking connectivity... done.
$ cd activemq-artemis
</code></pre></li>
<li><p>Add a remote reference to <code>upstream</code> for pulling future updates</p>
<pre><code> $ git remote add upstream https://github.com/apache/activemq-artemis
</code></pre></li>
<li><p>Build with Maven</p>
<p>Typically developers will want to build using the <code>dev</code> profile which enables license and code style checks. For
example:</p>
<pre><code> $ mvn -Pdev install
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] ActiveMQ Artemis Parent ........................... SUCCESS [2.298s]
[INFO] ActiveMQ Artemis Commons .......................... SUCCESS [1.821s]
[INFO] ActiveMQ Artemis Selector Implementation .......... SUCCESS [0.767s]
[INFO] ActiveMQ Artemis Native POM ....................... SUCCESS [0.189s]
[INFO] ActiveMQ Artemis Journal .......................... SUCCESS [0.646s]
[INFO] ActiveMQ Artemis Core Client ...................... SUCCESS [5.969s]
[INFO] ActiveMQ Artemis JMS Client ....................... SUCCESS [2.110s]
[INFO] ActiveMQ Artemis Server ........................... SUCCESS [11.540s]
...
[INFO] ActiveMQ Artemis stress Tests ..................... SUCCESS [0.332s]
[INFO] ActiveMQ Artemis performance Tests ................ SUCCESS [0.174s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
</code></pre></li>
</ol>
<h2 id="typical-development-cycle">Typical development cycle</h2>
<ol>
<li><p>Identify a task (e.g. a bug to fix or feature to implement)</p>
<p><a href="https://issues.apache.org/jira/browse/ARTEMIS" target="_blank">https://issues.apache.org/jira/browse/ARTEMIS</a></p>
</li>
<li><p>Create a topic branch in your local git repo to do your work</p>
<pre><code> $ git checkout -b my_cool_feature
</code></pre></li>
<li><p>Make the changes and commit one or more times</p>
<pre><code> $ git commit
</code></pre><p><a name="commitMessageDetails"></a> When you commit your changes you will need to supply a commit message. We follow the
50/72 git commit message format. An ActiveMQ Artemis commit message should be formatted in the following manner:</p>
<ol>
<li>Add the ARTEMIS JIRA (if one exists) followed by a brief description of the change in the first line. This line
should be limited to 50 characters.</li>
<li>Insert a single blank line after the first line.</li>
<li>Provide a detailed description of the change in the following lines, breaking paragraphs where needed. These lines
should be wrapped at 72 characters.</li>
</ol>
<p>An example correctly formatted commit message:</p>
<pre><code> ARTEMIS-123 Add new commit msg format to README
Adds a description of the new commit message format as well as examples
of well formatted commit messages to the README.md. This is required
to enable developers to quickly identify what the commit is intended to
do and why the commit was added.
</code></pre></li>
<li><p>Occasionally you&apos;ll want to push your commit(s) to GitHub for safe-keeping and/or sharing with others.</p>
<pre><code> git push origin my_cool_feature
</code></pre><p>Note that git push references the branch you are pushing and defaults to <code>master</code>, not your working branch.</p>
</li>
<li><p>Discuss your planned changes (if you want feedback)</p>
<p>On mailing list - <a href="http://activemq.apache.org/mailing-lists.html" target="_blank">http://activemq.apache.org/mailing-lists.html</a>
On IRC - irc://irc.freenode.org/apache-activemq or <a href="https://webchat.freenode.net/?channels=apache-activemq" target="_blank">https://webchat.freenode.net/?channels=apache-activemq</a></p>
</li>
<li><p>Once you&apos;re finished coding your feature/fix then rebase your branch against the latest master (applies your patches
on top of master)</p>
<pre><code> git fetch upstream
git rebase -i upstream/master
# if you have conflicts fix them and rerun rebase
# The -f, forces the push, alters history, see note below
git push -f origin my_cool_feature
</code></pre><p>The <code>rebase -i</code> triggers an interactive update which also allows you to combine commits, alter commit messages etc.
It&apos;s a good idea to make the commit log very nice for external consumption (e.g. by squashing all related commits
into a single commit. Note that rebasing and/or using <code>push -f</code> can alter history. While this is great for making a
clean patch, it is unfriendly to anyone who has forked your branch. Therefore you&apos;ll want to make sure that you
either work in a branch that you don&apos;t share, or if you do share it, tell them you are about to revise the branch
history (and thus, they will then need to rebase on top of your branch once you push it out).</p>
</li>
<li><p>Get your changes merged into upstream</p>
<ol>
<li>Send a GitHub pull request, by clicking the pull request link while in your repo&apos;s fork.</li>
<li>An email will automatically be sent to the ActiveMQ developer list.</li>
<li>As part of the review you may see an automated test run comment on your request.</li>
<li>After review a maintainer will merge your PR into the canonical git repository at which point those changes will
be synced with the GitHub mirror repository (i.e. your <code>master</code>) and your PR will be closed by the <code>asfgit</code> bot.</li>
</ol>
</li>
</ol>
<h2 id="other-common-tasks">Other common tasks</h2>
<ol>
<li><p>Pulling updates from upstream</p>
<pre><code> $ git pull --rebase upstream master
</code></pre><p>(<code>--rebase</code> will automatically move your local commits, if any, on top of the latest branch you pull from; you can leave
it off if you do not have any local commits).</p>
<p>One last option, which some prefer, is to avoid using pull altogether, and just use fetch + rebase (this is of course
more typing). For example:</p>
<pre><code> $ git fetch upstream
$ git pull
</code></pre></li>
<li><p>Pushing pulled updates (or local commits if you aren&apos;t using topic branches) to your private GitHub repo (origin)</p>
<pre><code> $ git push
Counting objects: 192, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (44/44), done.
Writing objects: 100% (100/100), 10.67 KiB, done.
Total 100 (delta 47), reused 100 (delta 47)
To git@github.com:&lt;your-user-name&gt;/apache-artemis.git
3382570..1fa25df master -&gt; master
</code></pre><p>You might need to say -f to force the changes.</p>
</li>
</ol>
<h2 id="adding-new-dependencies">Adding New Dependencies</h2>
<p>Due to incompatibilities between some open source licenses and the Apache v2.0 license (that this project is licensed under)
care must be taken when adding new dependencies to the project. The Apache Software Foundation 3rd party licensing
policy has more information here: <a href="https://www.apache.org/legal/3party.html" target="_blank">https://www.apache.org/legal/3party.html</a></p>
<p>To keep track of all licenses in ActiveMQ Artemis, new dependencies must be added in either the top level pom.xml or in test/pom.xml
(depending on whether this is a test only dependency or if it is used in the main code base). The dependency should be
added under the dependency management section with version and labelled with a comment highlighting the license for the
dependency version. See existing dependencies in the main pom.xml for examples. The dependency can then be added to
individual ActiveMQ Artemis modules <em>without</em> the version specified (the version is implied from the dependency management
section of the top level pom). This allows ActiveMQ Artemis developers to keep track of all dependencies and licenses.</p>
</section>
</div>
<div class="search-results">
<div class="has-results">
<h1 class="search-results-title"><span class='search-results-count'></span> results matching "<span class='search-query'></span>"</h1>
<ul class="search-results-list"></ul>
</div>
<div class="no-results">
<h1 class="search-results-title">No results matching "<span class='search-query'></span>"</h1>
</div>
</div>
</div>
</div>
</div>
</div>
<a href="notice.html" class="navigation navigation-prev " aria-label="Previous page: Legal Notice">
<i class="fa fa-angle-left"></i>
</a>
<a href="ide.html" class="navigation navigation-next " aria-label="Next page: IDE Integration">
<i class="fa fa-angle-right"></i>
</a>
</div>
<script>
var gitbook = gitbook || [];
gitbook.push(function() {
gitbook.page.hasChanged({"page":{"title":"Working with the Code","level":"1.3","depth":1,"next":{"title":"IDE Integration","level":"1.4","depth":1,"path":"ide.md","ref":"ide.md","articles":[]},"previous":{"title":"Legal Notice","level":"1.2","depth":1,"path":"notice.md","ref":"notice.md","articles":[]},"dir":"ltr"},"config":{"plugins":[],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"highlight":{},"search":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"sharing":{"facebook":true,"twitter":true,"google":false,"weibo":false,"instapaper":false,"vk":false,"all":["facebook","google","twitter","weibo","instapaper"]},"fontsettings":{"theme":"white","family":"sans","size":2},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":false}},"github":"apache/activemq-artemis","theme":"default","githubHost":"https://github.com/","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"ActiveMQ Artemis Documentation","links":{"home":"http://activemq.apache.org/artemis","issues":"https://issues.apache.org/jira/browse/ARTEMIS","contribute":"http://activemq.apache.org/contributing.html"},"gitbook":"3.x.x","description":"ActiveMQ Artemis Hacking Guide"},"file":{"path":"code.md","mtime":"2020-01-10T14:13:27.000Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2020-01-10T14:51:15.876Z"},"basePath":".","book":{"language":""}});
});
</script>
</div>
<script src="gitbook/gitbook.js"></script>
<script src="gitbook/theme.js"></script>
<script src="gitbook/gitbook-plugin-search/search-engine.js"></script>
<script src="gitbook/gitbook-plugin-search/search.js"></script>
<script src="gitbook/gitbook-plugin-lunr/lunr.min.js"></script>
<script src="gitbook/gitbook-plugin-lunr/search-lunr.js"></script>
<script src="gitbook/gitbook-plugin-sharing/buttons.js"></script>
<script src="gitbook/gitbook-plugin-fontsettings/fontsettings.js"></script>
</body>
</html>