<commit_before>= How to develop on Hawkular
<NAME>
2015-02-26
:description: Hacking on Hawkular
:icons: font
:jbake-type: page
:jbake-status: published
:toc: macro
:toc-title:


toc::[]

== Developing Hawkular

Hawkular is a set of projects and sub-projects developed together and than assembled in the Hawkular integration
project.

The biggest part of the Hawkular server code is written in Java 8.
Project assembly is run via Apache Maven.

The UI code consists mostly of AngularJS directives written in Typescript and then translated into JavaScript.

== Components

[cols="4*", options="header"]
|===
|Name|GitHub|Bug tracking|Description
|Hawkular|https://github.com/hawkular/hawkular|https://issues.jboss.org/browse/HAWKULAR|The “glue” use all
components to build the hawkular solution, this is the project that users would build and run, it consumes all the components.
|Hawkular-Alerts|https://github.com/hawkular/hawkular-alerts|https://issues.jboss.org/browse/HWKALERTS|Model and services to model and define alerts. It also runs the engine to tell when an alert needs to be triggered.
|Hawkular-Metrics|https://github.com/hawkular/hawkular-metrics|https://issues.jboss.org/browse/HWKMETRICS|Model and service for metrics and availability storage.
|Hawkular-Bus|https://github.com/hawkular/hawkular-bus|https://issues.jboss.org/browse/HWKBUS|Communication back bone
|Hawkular-Inventory|https://github.com/hawkular/hawkular-inventory|https://issues.jboss.org/browse/HWKINVENT|In charge of modeling the various components to monitor and their relationships.
|Hawkular-Build-Tools|https://github.com/hawkular/hawkular-build-tools|https://issues.jboss.org/browse/HAWKULAR|Various tools to help for the build, contains checkstyle definitions for instance
|Hawkular-Accounts|https://github.com/hawkular/hawkular-accounts|https://issues.jboss.org/browse/HAWKULAR|Authorization framework for Hawkular components.
|===

== Building

Each hawkular component should be buildable on its own, but may have dependencies on other components.
We regularly publish snapshots into the JBoss Nexus snapshot repository.

=== Full distribution

To build the full distribution, you need to check out the main hawkular repo

[source,shell]
----
git clone https://github.com/hawkular/hawkular.git
cd hawkular
mvn install -Pdev -Dlicense.skip
cd kettle/target
cd wildfly-8.2.0.Final
bin/standalone.sh
----

When the server is running you can hit the UI at http://localhost:8080/

When you build the Kettle, all sub-components are deployed to
`modules/system/layers/base/org/hawkular/nest/main/deployments/` inside the WildFly server.

[TIP]
--
If you want to hot-deploy your component during development, you need to enable the deployment scanner. You can do this
via the JBoss CLI by running this command:
[source,shell]
----
bin/jboss-cli.sh --connect --command='/subsystem=deployment-scanner/scanner=default/:write-attribute(name=scan-enabled,value=true)'
----
'''
You can set this manually by editing `standalone/configuration/standalone.xml` and setting `<deployment-scanner scan-enabled="true" ...`.
Once the scanner is enabled, you need to remove the respective component from the above modules directory. Now you can copy your component's deployment into the scanner's deployment directory at `standalone/deployments/`.
--

TIP: If you want to attach a remote debugger, you can start the server with `--debug` option like this:
`bin/standalone.sh --debug`

== Hack the code

When you decide you want to start coding on Hawkular and/or one of the sub-projects mentioned above, please visit the
 https://github.com/hawkular/hawkular-build-tools/tree/master/ide-configs[ide-configs] section of the
 build-tools repository and download the respective settings file for your IDE. This settings file will help you
 applying the coding standards that are checked on `mvn install` runs.

To work on the code, it is best to fork the Hawkular repository and then work there on your changes.

TIP: Try to work in branches even inside your own repository, as this will make syncing with upstream
 much easier.

Once you have made a change ready to go, go to the respective GitHub repository and open a pull-request (see below).

IMPORTANT: make sure to run a full `mvn clean install` run on your code changes without any other options and fix
any errors that appear.


TIP: If you work with Snapshot dependencies of other projects, it can be helpful to force check for updates with
maven option `-U`


== Submitting Pull-Requests

GitHub has the beautiful feature of Pull-Requests (PR). Once you are done with coding, commit and push the change to a
a new branch in your private fork. Then go to the fork on GitHub and your branch and open a Pull-Request. Please
describe your change before submitting.
GitHub has https://help.github.com/articles/using-pull-requests/[documentation on pull-requests]

When the Pull-Request has been submitted, expect some reviews, questions and suggestions. If this leads to
updated code, just push the additional commits to the branch you used to open the Pull-Request.

After the Pull-Request got merged into your branch you can delete it on GitHub with the "Delete branch button" on the
PR itself. To also remove it from the local repo, you can run `git fetch --prune` like this:

[source,shell]
----
snert:kettle hrupp$ git fetch --prune
From https://github.com/hawkular/hawkular
 x [deleted]         (none)     -> origin/pinger-update
----

== Reviewing/merging Pull-Requests

Before merging a Pull-Request, make sure that it builds when merged. The Hawkular repositories have been set up to
run continuous integration (CI) on Pull-Requests.

image::/img/dev-docs/pr-detail.png[Detail of a pull-request]

In above detail view of a pull-request, you can see that the first commit (e44f90a) failed CI by the red cross next
to the commit id. The commit after it then passed as you can see by the green check mark. Those markers are
shown for commits on the _Conversation_ and _Commits_ tab in the GitHub UI.

IMPORTANT: Only merge Pull-Requests that have successfully passed CI

The _Files Changed_ tab allow to review the commits as difference to the reference branch (usually master). It is
possible to comment on individual lines by hovering the mouse cursor on the line separator between lne numbers and
code until a little white plus on blue appears. Click on it and add your comment.

image::/img/dev-docs/pr-detail2.png[Add a line comment]

If you have opened a comment, allow the submitter (and others) to reply and potentially update the code.

After everything looks good, press the big green merge button :-)


== Code Style

As already mentioned above, there are some coding conventions enforced by checkstyle. Please follow them. Using one of
the IDE setup files will help you. Other than that there are other conventions we should follow

* DO not throw `NullPointerException` when method arguments are `null`. Throw `IllegalArgumentException` instead.
* Always use the loggers from `org.jboss.logging`


== Documentation

Documentation such as these pages, but also all the README files are written in AsciiDoc and use a file suffix of
`.adoc`.

Jax-RS Rest-Interfaces are to be commented / annotated via Swagger Annotations, that allow for automatic creation of
API documentation from the annotations and the Java elements they are applied to.<commit_msg>Add a line about package names and remove mentioning -Pdev.<commit_after>= How to develop on Hawkular
<NAME>
2015-02-26
:description: Hacking on Hawkular
:icons: font
:jbake-type: page
:jbake-status: published
:toc: macro
:toc-title:


toc::[]

== Developing Hawkular

Hawkular is a set of projects and sub-projects developed together and than assembled in the Hawkular integration
project.

The biggest part of the Hawkular server code is written in Java 8.
Project assembly is run via Apache Maven.

The UI code consists mostly of AngularJS directives written in Typescript and then translated into JavaScript.

== Components

[cols="4*", options="header"]
|===
|Name|GitHub|Bug tracking|Description
|Hawkular|https://github.com/hawkular/hawkular|https://issues.jboss.org/browse/HAWKULAR|The “glue” use all
components to build the hawkular solution, this is the project that users would build and run, it consumes all the components.
|Hawkular-Alerts|https://github.com/hawkular/hawkular-alerts|https://issues.jboss.org/browse/HWKALERTS|Model and services to model and define alerts. It also runs the engine to tell when an alert needs to be triggered.
|Hawkular-Metrics|https://github.com/hawkular/hawkular-metrics|https://issues.jboss.org/browse/HWKMETRICS|Model and service for metrics and availability storage.
|Hawkular-Bus|https://github.com/hawkular/hawkular-bus|https://issues.jboss.org/browse/HWKBUS|Communication back bone
|Hawkular-Inventory|https://github.com/hawkular/hawkular-inventory|https://issues.jboss.org/browse/HWKINVENT|In charge of modeling the various components to monitor and their relationships.
|Hawkular-Build-Tools|https://github.com/hawkular/hawkular-build-tools|https://issues.jboss.org/browse/HAWKULAR|Various tools to help for the build, contains checkstyle definitions for instance
|Hawkular-Accounts|https://github.com/hawkular/hawkular-accounts|https://issues.jboss.org/browse/HAWKULAR|Authorization framework for Hawkular components.
|===

== Building

Each hawkular component should be buildable on its own, but may have dependencies on other components.
We regularly publish snapshots into the JBoss Nexus snapshot repository.

=== Full distribution

To build the full distribution, you need to check out the main hawkular repo

[source,shell]
----
git clone https://github.com/hawkular/hawkular.git
cd hawkular
mvn install -Dlicense.skip
cd kettle/target
cd wildfly-8.2.0.Final
bin/standalone.sh
----

When the server is running you can hit the UI at http://localhost:8080/

When you build the Kettle, all sub-components are deployed to
`modules/system/layers/base/org/hawkular/nest/main/deployments/` inside the WildFly server.

[TIP]
--
If you want to hot-deploy your component during development, you need to enable the deployment scanner. You can do this
via the JBoss CLI by running this command:
[source,shell]
----
bin/jboss-cli.sh --connect --command='/subsystem=deployment-scanner/scanner=default/:write-attribute(name=scan-enabled,value=true)'
----
'''
You can set this manually by editing `standalone/configuration/standalone.xml` and setting `<deployment-scanner scan-enabled="true" ...`.
Once the scanner is enabled, you need to remove the respective component from the above modules directory. Now you can copy your component's deployment into the scanner's deployment directory at `standalone/deployments/`.
--

TIP: If you want to attach a remote debugger, you can start the server with `--debug` option like this:
`bin/standalone.sh --debug`

== Hack the code

When you decide you want to start coding on Hawkular and/or one of the sub-projects mentioned above, please visit the
 https://github.com/hawkular/hawkular-build-tools/tree/master/ide-configs[ide-configs] section of the
 build-tools repository and download the respective settings file for your IDE. This settings file will help you
 applying the coding standards that are checked on `mvn install` runs.

To work on the code, it is best to fork the Hawkular repository and then work there on your changes.

TIP: Try to work in branches even inside your own repository, as this will make syncing with upstream
 much easier.

Once you have made a change ready to go, go to the respective GitHub repository and open a pull-request (see below).

IMPORTANT: make sure to run a full `mvn clean install` run on your code changes without any other options and fix
any errors that appear.


TIP: If you work with Snapshot dependencies of other projects, it can be helpful to force check for updates with
maven option `-U`


== Submitting Pull-Requests

GitHub has the beautiful feature of Pull-Requests (PR). Once you are done with coding, commit and push the change to a
a new branch in your private fork. Then go to the fork on GitHub and your branch and open a Pull-Request. Please
describe your change before submitting.
GitHub has https://help.github.com/articles/using-pull-requests/[documentation on pull-requests]

When the Pull-Request has been submitted, expect some reviews, questions and suggestions. If this leads to
updated code, just push the additional commits to the branch you used to open the Pull-Request.

After the Pull-Request got merged into your branch you can delete it on GitHub with the "Delete branch button" on the
PR itself. To also remove it from the local repo, you can run `git fetch --prune` like this:

[source,shell]
----
snert:kettle hrupp$ git fetch --prune
From https://github.com/hawkular/hawkular
 x [deleted]         (none)     -> origin/pinger-update
----

== Reviewing/merging Pull-Requests

Before merging a Pull-Request, make sure that it builds when merged. The Hawkular repositories have been set up to
run continuous integration (CI) on Pull-Requests.

image::/img/dev-docs/pr-detail.png[Detail of a pull-request]

In above detail view of a pull-request, you can see that the first commit (e44f90a) failed CI by the red cross next
to the commit id. The commit after it then passed as you can see by the green check mark. Those markers are
shown for commits on the _Conversation_ and _Commits_ tab in the GitHub UI.

IMPORTANT: Only merge Pull-Requests that have successfully passed CI

The _Files Changed_ tab allow to review the commits as difference to the reference branch (usually master). It is
possible to comment on individual lines by hovering the mouse cursor on the line separator between lne numbers and
code until a little white plus on blue appears. Click on it and add your comment.

image::/img/dev-docs/pr-detail2.png[Add a line comment]

If you have opened a comment, allow the submitter (and others) to reply and potentially update the code.

After everything looks good, press the big green merge button :-)


== Code Style

As already mentioned above, there are some coding conventions enforced by checkstyle. Please follow them. Using one of
the IDE setup files will help you. Other than that there are other conventions we should follow

* DO not throw `NullPointerException` when method arguments are `null`. Throw `IllegalArgumentException` instead.
* Always use the loggers from `org.jboss.logging`
* Use Java-standard package names, all lower case as in `org.hawkular.my.coolpackage`, `org.hawkular.mycoolpackage` or
 `org.hawkular.my.cool.package`. Do not use camelCase. Use underscores only if the name would otherwise be illegal.


== Documentation

Documentation such as these pages, but also all the README files are written in AsciiDoc and use a file suffix of
`.adoc`.

Jax-RS Rest-Interfaces are to be commented / annotated via Swagger Annotations, that allow for automatic creation of
API documentation from the annotations and the Java elements they are applied to.
{'fraction_non_alphanumeric': 0.07408145638163577, 'fraction_numerical': 0.0029233937944322637, 'mean_word_length': 4.529757531227039, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 36, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4765051', 'n_tokens_mistral': 4264, 'n_tokens_neox': 4053, 'n_words': 1922}