<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
Hacking on AS7
</h3>
<span style="margin-bottom: 10px;">
modified by <a href="http://community.jboss.org/people/maeste">Stefano Maestri</a> in <i>JBoss AS7 Development</i> - <a href="http://community.jboss.org/docs/DOC-15596">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><h4>1. Create a github account</h4><p><a class="jive-link-external-small" href="http://github.com">http://github.com</a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h4>2. Fork jboss-as into your account</h4><p><a class="jive-link-external-small" href="http://github.com/jbossas/jboss-as">http://github.com/jbossas/jboss-as<br/></a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h4>3. Clone your newly forked copy onto your local workspace</h4><div> </div><pre class="jive-pre"><code class="jive-code">
$ git clone git@github.com:[your user]/jboss-as.git
Initialized empty Git repository in /devel/jboss-as/.git/
remote: Counting objects: 2444, done.
remote: Compressing objects: 100% (705/705), done.
remote: Total 2444 (delta 938), reused 2444 (delta 938)
Receiving objects: 100% (2444/2444), 1.71 MiB | 205 KiB/s, done.
Resolving deltas: 100% (938/938), done.
$ cd jboss-as
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h4>4. Add a remote ref to upstream, for pulling future updates</h4><pre class="jive-pre"><code class="jive-code">git remote add upstream git://github.com/jbossas/jboss-as.git
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h4>5. Use maven (via build.sh) (make sure you use maven 3)</h4><pre class="jive-pre"><code class="jive-code">$ ./build.sh install
.....
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] JBoss Application Server: BOM ..................... SUCCESS [1.834s]
[INFO] JBoss Application Server: Parent Aggregator ....... SUCCESS [0.022s]
[INFO] JBoss Application Server: Domain Core ............. SUCCESS [3.051s]
[INFO] JBoss Application Server: Server Manager .......... SUCCESS [0.204s]
[INFO] JBoss Application Server: Server .................. SUCCESS [0.283s]
[INFO] JBoss Application Server: Domain Controller ....... SUCCESS [0.084s]
[INFO] JBoss Application Server: Process Manager ......... SUCCESS [0.314s]
[INFO] JBoss Application Server: Remoting ................ SUCCESS [0.390s]
[INFO] JBoss Application Server: Build ................... SUCCESS [5.696s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h4>6. Pulling later updates from upstream</h4><pre class="jive-pre"><code class="jive-code">$ git pull --rebase upstream master
>From git://github.com/jbossas/jboss-as
* branch            master     -> FETCH_HEAD
Updating 3382570..1fa25df
Fast-forward
{parent => bom}/pom.xml                            |   70 ++++----------
build/pom.xml                                      |   13 +--
domain/pom.xml                                     |   10 ++
.../src/main/resources/examples/host-example.xml   |    2 +-
.../resources/examples/jboss-domain-example.xml    |   28 +++---
.../main/resources/schema/jboss-domain-common.xsd  |   12 +--
.../main/resources/schema/jboss-domain-host.xsd    |    2 +-
domain/src/main/resources/schema/jboss-domain.xsd  |   17 ++--
pom.xml                                            |  100 ++++++++++++++++++--
process-manager/pom.xml                            |    3 +-
10 files changed, 156 insertions(+), 101 deletions(-)
rename {parent => bom}/pom.xml (85%)
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: monospace;"><strong style="font-weight: bold;">(--rebase will automatically put move commits, if you have any, on top of the latest master, you can leave it off if you do not). Please note that --rebase is very important if you have commits. What happens is that when git pull can't fast forward, it does a merge commit, and a merge commit puts the sucked in changes ON TOP of yours whereas a rebase puts them BELOW yours. In other words - the branch gets all messed up <span> :) </span> and rebasing against latest master (see point 12) will be a lot of pain. To don't forget --rebase option you may want to create an alias</strong></span></p><p><span style="font-family: monospace;"><strong style="font-weight: bold;"><br/></strong></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"><span style="font-family: monospace;"> </span> </p><p><span style="font-family: monospace;"><pre class="jive-pre"><code class="jive-code"> $ git config --global alias.up "pull --rebase"</code></pre></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: monospace;"><strong style="font-weight: bold;">and then just use the new alias instead of pull</strong></span></p><p><span style="font-family: monospace;"><strong style="font-weight: bold;"><br/></strong><pre class="jive-pre"><code class="jive-code"> $ git up upstream master
</code></pre></span></p><h4>7. Pushing pulled updates (or local commits if you aren't using topic branches) to your private github repo (origin)</h4><pre class="jive-pre"><code class="jive-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:[your user]/jboss-as.git
   3382570..1fa25df  master -> master
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><strong style="font-weight: bold;">You might need to say -f to force the changes. Read the note on 12 though before you do it.</strong></p><h4>8. Discuss your planned changes (if you want feedback)</h4><ul><li>On the forums - <a class="" href="http://community.jboss.org/en/jbossas/dev/jboss_as7_development">http://community.jboss.org/en/jbossas/dev/jboss_as7_development</a></li><li>On IRC - <a class="jive-link-anchor-small">irc://irc.freenode.org/jboss-as7</a><span> or <a class="jive-link-external-small" href="http://webchat.freenode.net/?channels=jboss-as7">https://webchat.freenode.net/?channels=jboss-as7</a></span></li></ul><h4>9. Make sure there is a JIRA somewhere for the enhancement/fix</h4><p><a class="jive-link-external-small" href="http://jira.jboss.org">http://jira.jboss.org</a></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h4>10. Create a simple topic branch to isolate that work (just a recommendation)</h4><pre class="jive-pre"><code class="jive-code">git checkout -b my_cool_feature
</code></pre><h6>Note: See tips section for how to use a nice git prompt for tracking what branch you are in!</h6><h6>11. Make the changes and commit one or more times (Don't forget to push)</h6><pre class="jive-pre"><code class="jive-code">git commit -m 'JBAS-XXXX Frunubucate the Fromungulator'
git commit -m 'JBAS-YYYY Tripple Performance of Fromungulation'
git push my_cool_feature
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><em style="font-style: italic;">Note that git push references the branch you are pushing and defaults to master,<strong style="font-weight: bold;"> not your working branch</strong>.</em></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h4>12. Rebase your branch against the latest master (applies your patches on top of master)</h4><pre class="jive-pre"><code class="jive-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 my_cool_feature
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The -i triggers an interactive update which also allows you to combine commits, alter commit messages etc. It's a good idea to make the commit log very nice for external consumption. Note that this alters history, which while great for making a clean patch, is unfriendly to anyone who has forked your branch. Therefore you want to make sure that you either work in a branch that you don'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><h4>13. Get your changes merged into upstream</h4><ol><li>Make sure your repo is in sync with other unrelated changes in upstream before requesting your changes be merged into upstream by repeating  step 12.</li><li><span>Email a pull request to </span><a class="jive-link-email-small" href="mailto:jbossas-pull-requests@lists.jboss.org" target="_blank">jbossas-pull-requests@lists.jboss.org</a><span> (if I haven't subscribed the list, do it </span><a class="jive-link-external-small" href="https://lists.jboss.org/mailman/listinfo/jbossas-pull-requests">here</a><span>) with a link to your repo, a description of the changes, and who reviewed (if any)</span></li><li>After review a maintainer will merge your patch, update/resolve issues by request, and reply when complete</li><li>Don't forget to switch back to master and pull the updates<ol><li><pre class="jive-pre"><code class="jive-code">git checkout master
git pull upstream master
</code></pre></li></ol></li></ol><p><span style="white-space: pre; font-family: monospace; "><br/></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h4>Appendix A.  Adding a new external dependency</h4><ol><li>Edit pom.xml and add a property of the form "version.groupId.artifactId" which contains the Maven version of the dependency.  Add your dependency to the <dependencyManagement> section, and use the property for the version.  If your new dependency has any transitive dependencies, be sure to <exclude> them (or if possible, update the project so that all its dependencies are of <strong style="font-weight: bold;">provided</strong> scope).</li><li>Add your dependency to any AS modules that require it, but only with group/artifact.</li><li>Edit build/pom.xml and add your dependency with only group/artifact.</li><li>Create a directory in build/src/modules corresponding to the <strong style="font-weight: bold;">module's</strong> name (which will differ from the Maven group/artifact name; look at other modules to get a feel for the naming scheme), with a version of "main", like this: "build/src/modules/org/jboss/foo/main".</li><li>Create a module.xml file inside the "main" directory.  Use a module.xml from another similar module as a template.</li><li>Edit build/build.xml and add a <module-def> element.  The name listed in the <module-def> element corresponds to the <strong style="font-weight: bold;">module</strong> name.  The group/artifact listed in the nested maven-resource element(s) refer to the <strong style="font-weight: bold;">Maven</strong> group/artifact name.</li><li><strong style="font-weight: bold;">Important:</strong> Make sure you did not introduce any transitive dependencies by using "mvn dependency:tree".  If you did, be sure to add <exclusion>s for each of them to your dependency as described above.</li></ol><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Please be sure to preserve the alphabetical ordering of all POMs and the build.xml file.</p><h4>Appendix B.  Adding a new AS submodule</h4><ol><li>Create the directory corresponding to the submodule and add it to the root pom.xml file.  The convention is to leave off the "jboss-as-" portion, so "jboss-as-remoting" becomes "remoting".</li><li>Create a POM for your submodule (use another submodule as a template).  Make sure all dependencies you specify do <strong style="font-weight: bold;">not</strong> include a version.  The group ID should be "org.jboss.as", and the artifact ID should begin with "jboss-as-" and there should be a proper <name> for the new module.</li><li>Add the new submodule to the top section of the <dependencyManagement> of the top-level pom.xml.  The version should be set to "${project.version}".  This section is sorted alphabetically by artifact name so please preserve that ordering.</li><li>Add your submodule dependency to any AS modules that require it, but only with group/artifact.</li><li>Edit build/pom.xml and add the new submodule with only group/artifact.</li><li>Create a directory in build/src/modules corresponding to the submodule, with a version of "main", like this: "build/src/modules/org/jboss/as/new-subsystem/main".</li><li>Create a module.xml file inside the "main" directory.  Use a module.xml from another subsystem as a template.</li><li>Edit build/build.xml and add a <module-def> element for the subsystem.  Use the module name and Maven coordinates from steps 6 and 2 respectively.  Use another submodule as a template.</li></ol><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Please be sure to preserve the alphabetical ordering of all POMs and the build.xml file.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h4>Appendix C.  Profiling with JProfiler</h4><p>Performance tuning is an important part of AS7 development.  In order to use JProfiler on a standalone AS 7 instance, first you need to add the following to your standalone.conf file:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=com.jprofiler -agentlib:jprofilerti -Xbootclasspath/a:/path/to/jprofiler/bin/agent.jar"
</code></pre><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>The "jboss.modules.system.pkgs" property tells JBoss Modules to allow the "com.profiler" classes to be found from any class loader, which is essential to allow the JProfiler agent to run.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>It's easiest to then just set up your JProfiler session as "Remote", and start the server and the profiler in any order.  That's it!</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><h4>Tips & Tricks!</h4><h4>Creating a Git status prompt in your terminal</h4><p>This makes it easy to not forget what branch you are working in and quickly tell if you have changes. The following will adjust the PS1 on unix (or cygwin on Windows). Note that it assumes a compiled version of git, which is also the case for the OSX packages. If you are using the bundled rpm version, change the completion path to "/etc/bash_completion.d/git"</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><pre class="jive-pre"><code class="jive-code">GIT_COMPLETION_PATH="/usr/local/git/contrib/completion/git-completion.bash"
if [ -f "$GIT_COMPLETION_PATH" ]; then
   GIT_PS1_SHOWDIRTYSTATE=true
   . "$GIT_COMPLETION_PATH"
   ADD_PS1='$(__git_ps1)'
fi
if [[ ${EUID} == 0 ]] ; then
      PS1="\[\033[01;31m\]\h\[\033[01;34m\] \w\[\033[33m\]$ADD_PS1\[\033[34m\] \$\[\033[00m\] "
else
      PS1="\[\033[01;32m\]\u@\h\[\033[01;34m\] \w\[\033[33m\]$ADD_PS1\[\033[34m\] \$\[\033[00m\] "
fi
</code></pre></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-15596">going to Community</a></p>
<p style="margin: 0;">Create a new document in JBoss AS7 Development at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2225">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>