= Working with the Code

While the canonical Apache ActiveMQ Artemis git repository is hosted on Apache hardware at https://gitbox.apache.org/repos/asf/activemq-artemis.git 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.

If you do not wish to use GitHub for whatever reason you can follow the overall process outlined in the "Typical development cycle" section below but instead attach https://git-scm.com/docs/git-format-patch[a patch file] to the related JIRA or an email to the http://activemq.apache.org/mailing-lists.html[dev list].

== Initial Steps

. Create a GitHub account if you don't have one already
+
https://github.com

. Fork the apache-artemis repository into your account
+
https://github.com/apache/activemq-artemis

. Clone your newly forked copy onto your local workspace:
+
[,sh]
----
$ git clone git@github.com:<your-user-name>/activemq-artemis.git
Cloning into 'activemq-artemis'...
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
----
. Add a remote reference to `upstream` for pulling future updates
+
[,sh]
----
$ git remote add upstream https://github.com/apache/activemq-artemis
----
. Build with Maven
+
Typically developers will want to build using the `dev` profile which enables license and code style checks.
For example:
+
[,sh]
----
$ 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] ------------------------------------------------------------------------
----

== Typical development cycle

. Identify a task (e.g. a bug to fix or feature to implement)
+
https://issues.apache.org/jira/browse/ARTEMIS

. Create a topic branch in your local git repo to do your work
+
[,console]
----
$ git checkout -b my_cool_feature
----
. Make the changes and commit one or more times
+
[,console]
----
$ git commit
----
+
[#commitMessageDetails]
When you commit your changes you will need to supply a commit message.
We follow the  50/72 git commit message format as recommended in the https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project[official Git book].
An ActiveMQ Artemis commit message should be formatted in the following manner:

.. Add the first line with the summary, using maximum 50 characters.
Start the summary with the jira key (ARTEMIS-XXX) followed by a brief description of the change.
Use the prefix `NO-JIRA` only for a very small insignificant change, like a typo or a small doc fix.
Bug fixes, features or any code change, really should be accompanied by a jira, so they can clearly be reported in the release notes.
.. Insert a single blank line after the first line.
.. Provide a detailed description of the change in the following lines, breaking paragraphs where needed.
These lines should be wrapped at 72 characters.
+
An example correctly formatted commit message:
+
----
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.
----
. Occasionally you'll want to push your commit(s) to GitHub for safe-keeping and/or sharing with others.
+
[,console]
----
$ git push origin my_cool_feature
----
+
Note that git push references the branch you are pushing and defaults to `main`, not your working branch.

. https://activemq.apache.org/contact[Discuss your planned changes] (if you want feedback)
. Once you're finished coding your feature/fix then rebase your branch against the latest main (applies your patches  on top of main)
+
[,console]
----
$ git fetch upstream
$ git rebase -i upstream/main
----
If you have conflicts fix them and rerun `rebase`. The `-f` forces the push and alters history. See the note below
+
[,console]
----
$ git push -f origin my_cool_feature
----
+
The `rebase -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 (e.g.
by squashing all related commits  into a single commit.
Note that rebasing and/or using `push -f` can alter history.
While this is great for making a  clean patch, it is unfriendly to anyone who has forked your branch.
Therefore you'll 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).

. Get your changes merged into upstream
.. Send a GitHub pull request, by clicking the pull request link while in your repo's fork.
.. An email will automatically be sent to the ActiveMQ developer list.
.. As part of the review you may see an automated test run comment on your request.
.. 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 `main`) and your PR will be closed by the `asfgit` bot.

== Other common tasks

. Pulling updates from upstream
+
[,console]
----
$ git pull --rebase upstream main
----
+
(`--rebase` 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).
+
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:
+
[,console]
----
$ git fetch upstream
$ git pull
----
. Pushing pulled updates (or local commits if you aren't using topic branches) to your private GitHub repo (origin)
+
[,console]
----
$ 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-name>/apache-artemis.git
3382570..1fa25df  main -> main
----
+
You might need to specify `-f` to force the changes.

== Adding New Dependencies

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: https://www.apache.org/legal/3party.html

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 _without_ 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.