Skip to content

Latest commit

 

History

History
169 lines (121 loc) · 8.78 KB

code.md

File metadata and controls

169 lines (121 loc) · 8.78 KB
Raw

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 a patch file to the related JIRA or an email to the dev list.

Initial Steps

  1. Create a GitHub account if you don't have one already

    https://github.com

  2. Fork the apache-artemis repository into your account

    https://github.com/apache/activemq-artemis

  3. Clone your newly forked copy onto your local workspace:

     $ git clone [email protected]:<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

  4. Add a remote reference to upstream for pulling future updates

     $ git remote add upstream https://github.com/apache/activemq-artemis

  5. Build with Maven

    Typically developers will want to build using the dev profile which enables license and code style checks. For example:

     $ 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

  1. Identify a task (e.g. a bug to fix or feature to implement)

    https://issues.apache.org/jira/browse/ARTEMIS

  2. Create a topic branch in your local git repo to do your work

      $ git checkout -b my_cool_feature

  3. Make the changes and commit one or more times

      $ git commit

    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 official Git book. An ActiveMQ Artemis commit message should be formatted in the following manner:

    1. 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.
    2. Insert a single blank line after the first line.
    3. 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.

  4. Occasionally you'll want to push your commit(s) to GitHub for safe-keeping and/or sharing with others.

      git push origin my_cool_feature

    Note that git push references the branch you are pushing and defaults to main, not your working branch.

  5. Discuss your planned changes (if you want feedback)

  6. Once you're finished coding your feature/fix then rebase your branch against the latest main (applies your patches on top of main)

      git fetch upstream  
  git rebase -i upstream/main  
  # 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

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

  7. Get your changes merged into upstream

    1. Send a GitHub pull request, by clicking the pull request link while in your repo's fork.
    2. An email will automatically be sent to the ActiveMQ developer list.
    3. As part of the review you may see an automated test run comment on your request.
    4. 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

  1. Pulling updates from upstream

     $ 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:

     $ git fetch upstream
 $ git pull

  2. Pushing pulled updates (or local commits if you aren't using topic branches) to your private GitHub repo (origin)

     $ 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 [email protected]:<your-user-name>/apache-artemis.git  
    3382570..1fa25df  main -> main

    You might need to say -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.