1. Introduction

2. LegalNotice

3. WorkingwiththeCode

4. IDEIntegration

5. Building

6. Tests

7. CodeFormatting

8. Validatingreleases

9. NotesforMaintainers

10. History

TableofContents

ThishackingguideoutlineshowdeveloperscangetinvolvedincontributingtotheApacheActiveMQArtemisproject.

ApacheActiveMQArtemisHackingGuide

LicensedtotheApacheSoftwareFoundation(ASF)underoneormorecontributorlicenseagreements.SeetheNOTICE

filedistributedwiththisworkforadditionalinformationregardingcopyrightownership.TheASFlicensesthisfiletoYou

undertheApacheLicense,Version2.0(the"License");youmaynotusethisfileexceptincompliancewiththeLicense.You

mayobtainacopyoftheLicenseat

http://www.apache.org/licenses/LICENSE-2.0

Unlessrequiredbyapplicablelaworagreedtoinwriting,softwaredistributedundertheLicenseisdistributedonan"ASIS"

BASIS,WITHOUTWARRANTIESORCONDITIONSOFANYKIND,eitherexpressorimplied.SeetheLicenseforthe

specificlanguagegoverningpermissionsandlimitationsundertheLicense.

LegalNotice

WhilethecanonicalApacheActiveMQArtemisgitrepositoryishostedonApachehardwareathttps://git-wip-

us.apache.org/repos/asf?p=activemq-artemis.gitcontributorsareencouraged(butnotrequired)touseamirroronGitHub

forcollaborationandpull-requestreviewfunctionality.FollowthestepsbelowtogetsetupwithGitHub,etc.

IfyoudonotwishtouseGitHubforwhateverreasonyoucanfollowtheoverallprocessoutlinedinthe"Typical

developmentcycle"sectionbelowbutinsteadattachapatchfiletotherelatedJIRAoranemailtothedevlist.

1. CreateaGitHubaccountifyoudon'thaveonealready

http://github.com

2. Forktheapache-artemisrepositoryintoyouraccount

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

3. Cloneyournewlyforkedcopyontoyourlocalworkspace:

$gitclonegit@github.com:<your-user-name>/activemq-artemis.git

Cloninginto'activemq-artemis'...

remote:Countingobjects:63800,done.

remote:Compressingobjects:100%(722/722),done.

remote:Total63800(delta149),reused0(delta0),pack-reused62748

Receivingobjects:100%(63800/63800),18.28MiB|3.16MiB/s,done.

Resolvingdeltas:100%(28800/28800),done.

Checkingconnectivity...done.

$cdactivemq-artemis

4. Addaremotereferencetoupstreamforpullingfutureupdates

$gitremoteaddupstreamhttps://github.com/apache/activemq-artemis

5. BuildwithMaven

Typicallydeveloperswillwanttobuildusingthedevprofilewhichdisableslicenseandcodestylechecks.For

example:

$mvn-Pdevinstall

...

[INFO]------------------------------------------------------------------------

[INFO]ReactorSummary:

[INFO]

[INFO]ActiveMQArtemisParent...........................SUCCESS[2.298s]

[INFO]ActiveMQArtemisCommons..........................SUCCESS[1.821s]

[INFO]ActiveMQArtemisSelectorImplementation..........SUCCESS[0.767s]

[INFO]ActiveMQArtemisNativePOM.......................SUCCESS[0.189s]

[INFO]ActiveMQArtemisJournal..........................SUCCESS[0.646s]

[INFO]ActiveMQArtemisCoreClient......................SUCCESS[5.969s]

[INFO]ActiveMQArtemisJMSClient.......................SUCCESS[2.110s]

[INFO]ActiveMQArtemisServer...........................SUCCESS[11.540s]

...

[INFO]ActiveMQArtemisstressTests.....................SUCCESS[0.332s]

[INFO]ActiveMQArtemisperformanceTests................SUCCESS[0.174s]

[INFO]------------------------------------------------------------------------

[INFO]BUILDSUCCESS

[INFO]------------------------------------------------------------------------

WorkingwiththeCode

InitialSteps

1. Identifyatask(e.g.abugtofixorfeaturetoimplement)

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

2. Createatopicbranchinyourlocalgitrepotodoyourwork

$gitcheckout-bmy_cool_feature

3. Makethechangesandcommitoneormoretimes

$gitcommit

Whenyoucommityourchangesyouwillneedtosupplyacommitmessage.Wefollowthe50/72gitcommitmessage

format.AnActiveMQArtemiscommitmessageshouldbeformattedinthefollowingmanner:

i. AddtheARTEMISJIRA(ifoneexists)followedbyabriefdescriptionofthechangeinthefirstline.Thislineshould

belimitedto50characters.

ii. Insertasingleblanklineafterthefirstline.

iii. Provideadetaileddescriptionofthechangeinthefollowinglines,breakingparagraphswhereneeded.These

linesshouldbewrappedat72characters.

Anexamplecorrectlyformattedcommitmessage:

ARTEMIS-123AddnewcommitmsgformattoREADME

Addsadescriptionofthenewcommitmessageformataswellasexamples

ofwellformattedcommitmessagestotheREADME.md.Thisisrequired

toenabledeveloperstoquicklyidentifywhatthecommitisintendedto

doandwhythecommitwasadded.

4. Occasionallyyou'llwanttopushyourcommit(s)toGitHubforsafe-keepingand/orsharingwithothers.

gitpushoriginmy_cool_feature

Notethatgitpushreferencesthebranchyouarepushinganddefaultstomaster,notyourworkingbranch.

5. Discussyourplannedchanges(ifyouwantfeedback)

Onmailinglist-http://activemq.apache.org/mailing-lists.htmlOnIRC-irc://irc.freenode.org/apache-activemqor

https://webchat.freenode.net/?channels=apache-activemq

6. Onceyou'refinishedcodingyourfeature/fixthenrebaseyourbranchagainstthelatestmaster(appliesyourpatches

ontopofmaster)

gitfetchupstream

gitrebase-iupstream/master

#ifyouhaveconflictsfixthemandrerunrebase

#The-f,forcesthepush,altershistory,seenotebelow

gitpush-foriginmy_cool_feature

Therebase-itriggersaninteractiveupdatewhichalsoallowsyoutocombinecommits,altercommitmessagesetc.

Typicaldevelopmentcycle

It'sagoodideatomakethecommitlogveryniceforexternalconsumption(e.g.bysquashingallrelatedcommitsinto

asinglecommit.Notethatrebasingand/orusingpush-fcanalterhistory.Whilethisisgreatformakingaclean

patch,itisunfriendlytoanyonewhohasforkedyourbranch.Thereforeyou'llwanttomakesurethatyoueitherworkin

abranchthatyoudon'tshare,orifyoudoshareit,tellthemyouareabouttorevisethebranchhistory(andthus,they

willthenneedtorebaseontopofyourbranchonceyoupushitout).

7. Getyourchangesmergedintoupstream

i. SendaGitHubpullrequest,byclickingthepullrequestlinkwhileinyourrepo'sfork.

ii. AnemailwillautomaticallybesenttotheActiveMQdeveloperlist.

iii. Aspartofthereviewyoumayseeanautomatedtestruncommentonyourrequest.

iv. AfterreviewamaintainerwillmergeyourPRintothecanonicalgitrepositoryatwhichpointthosechangeswillbe

syncedwiththeGitHubmirrorrepository(i.e.yourmaster)andyourPRwillbeclosedbytheasfgitbot.

1. Pullingupdatesfromupstream

$gitpull--rebaseupstreammaster

(--rebasewillautomaticallymoveyourlocalcommits,ifany,ontopofthelatestbranchyoupullfrom;youcanleaveit

offifyoudonothaveanylocalcommits).

Onelastoption,whichsomeprefer,istoavoidusingpullaltogether,andjustusefetch+rebase(thisisofcoursemore

typing).Forexample:

$gitfetchupstream

$gitpull

2. Pushingpulledupdates(orlocalcommitsifyouaren'tusingtopicbranches)toyourprivateGitHubrepo(origin)

$gitpush

Countingobjects:192,done.

Deltacompressionusingupto4threads.

Compressingobjects:100%(44/44),done.

Writingobjects:100%(100/100),10.67KiB,done.

Total100(delta47),reused100(delta47)

Togit@github.com:<your-user-name>/apache-artemis.git

3382570..1fa25dfmaster->master

Youmightneedtosay-ftoforcethechanges.

DuetoincompatibilitiesbetweensomeopensourcelicensesandtheApachev2.0license(thatthisprojectislicensed

under)caremustbetakenwhenaddingnewdependenciestotheproject.TheApacheSoftwareFoundation3rdparty

licensingpolicyhasmoreinformationhere:http://www.apache.org/legal/3party.html

TokeeptrackofalllicensesinActiveMQArtemis,newdependenciesmustbeaddedineitherthetoplevelpom.xmlorin

test/pom.xml(dependingonwhetherthisisatestonlydependencyorifitisusedinthemaincodebase).Thedependency

shouldbeaddedunderthedependencymanagementsectionwithversionandlabelledwithacommenthighlightingthe

licenseforthedependencyversion.Seeexistingdependenciesinthemainpom.xmlforexamples.Thedependencycan

thenbeaddedtoindividualActiveMQArtemismoduleswithouttheversionspecified(theversionisimpliedfromthedependencymanagementsectionofthetoplevelpom).ThisallowsActiveMQArtemisdeveloperstokeeptrackofall

Othercommontasks

AddingNewDependencies

dependenciesandlicenses.

ThereafewfilesusefulforIDEintegrationunder./etc/ide-settingsonacheckedoutfolder.Thisfolderisnotpartofthe

sourcedistribution,butitcanbeeasilyobtained:

https://github.com/apache/activemq-artemis/tree/master/etc/ide-settings

ThefollowingstepsshowhowtoimportActiveMQArtemissourceintoIntelliJIDEAandsetupthecorrectmavenprofileto

allowrunningofJUnittestsfromwithintheIDE.(Stepsarebasedonversion:13.1.4)

File-->ImportProject-->SelecttherootdirectoryoftheActiveMQArtemissourcefolder.-->ClickOK

Thisshouldopentheimportprojectwizard.Fromhere:

Select"Importfromexistingmodel"togglebox,thenselectMavenfromthelistboxbelow.ClickNext.

Leavethedefaultssetonthispageandclicknext.

Onthe"Selectprofilespage",selectthecheckboxnextto"dev"andclicknext.

Fromherethedefaultsettingsshouldsuffice.Continuethroughthewizard,clickingnextuntilthewizardiscomplete.

OncetheprojecthasbeenimportedandIDEAhascaughtupimportingalltherelevantdependencies,youshouldbeable

torunJUnittestsfromwiththeIDE.Selectanytestclassinthetests->integrationtestsfolder.Rightclickontheclassin

theprojecttabandclick"Run".Ifthe"Run"optionispresentthenyou'reallsettogo.

IfyouarerunningIBMJDKitmaybealittletrickytogetitworking.

AfteryouaddtheJDKtotheIDE,addalsothevm.jarspecifictoyourplatformunderthatjdk.

(e.g:JAVA_HOME/jre/lib/amd64/default/jclSC180/vm.jar

There'saSOFQuestionaboutthisthatcouldbeusefulincaseyouarerunningintothisissue.

Wehavesharedthestyletemplatesthataregoodforthisproject.Ifyouwanttoapplythemusethesesteps:

File->ImportSettings

Selectthefileunder./artemis-cloned-folder/etc/ide-settings/idea/IDEA-style.jar

SelectbothCodeStyleTemplatesandFiletemplates(it'sthedefaultoption)

SelectOKandrestartIdea

Alternativelyyoucancopyartemis-codestyle.xmlunderyourhomesettingsatIntelliJIdea15/codestyles.

File->Settings->Editor->Inspections->Manage->Import

Selectthefile./artemis-cloned-folder/etc/ide-settings/idea/artemis-inspections.xml

SelectOK

IDEIntegration

IntelliJIDEA

ImportingtheProject

NoteaboutIBMJDKonIdea

StyleTemplatesandInspectionSettingsforIdea

Toimportinspectionsettings:

Ifthe"Run"or"Runalltests"optionisnotpresent.Itislikelythatthedefaultprofilehasnotbeenimportedproperly.To

(re)importthe"tests"Mavenprofileinanexistingproject.

OpentheMavenProjectsToolWindow:View->ToolWindows->MavenProjects

Selectthe"profiles"dropdown

Unselectthenreselectthecheckboxnextto"tests".

Clickonthe"Reimportallmavenprojects"buttoninthetoplefthandcornerofthewindow.(Itlookslikeacircularblue

arrow.

WaitforIDEAtoreloadandtryrunningaJUnittestagain.Theoptiontorunshouldnowbepresent.

WerecommendusingEclipseKepler(4.3),duetothebuilt-insupportforMavenandGit.Notethattherearestillsome

Mavenpluginsusedbysub-projects(e.g.documentation)whicharenotsupportedeveninEclipseKepler(4.3).

Eclipsem2eisalreadyincludedin"EclipseIDEforJavaDevelopers",oritcanbeinstalledfromEclipseKeplerrelease

repository.

Itisstronglyrecommendedtoturnofftheauto-updatingof.gitignorefilesbytheGitTeamextension.Otherwise,it

generatesnew.gitignorefilesinmanydirectoriesthatarenotneededduetothetoplevel.gitignorefile.Toturnitoff,goto

Preferences->Team->Git->Projectsanddeselectthe"Automaticallyignorederivedresources"checkbox.

ForproperschemavalidationyoucanaddtheArtemisschemastoyourEclipseXMLCatalog

Open:Window->Preferences->XML->XMLCatalog

SelectAdd->Workspace->Navigatetoartemis-serverandselectsrc/main/resources/schema/artemis-server.xsd->

clickOK

Repeattheabovestepsandaddsrc/main/resources/schema/artemis-configuration.xsd

YoucanimporttheArtemisCheckstyletemplateintoeclipsetodoCheckstylevalidation.Asaprerequisiteyouneedto

makesuretheCheckstylepluginisinstalledintoEclipsewhichyoucangetformtheEclipseMarketplace.Youalsowill

needtoconfigureSevntu-Checkstyle.Seehttp://sevntu-checkstyle.github.io/sevntu.checkstyle/forinstructions.Thento

configurethetemplate:

Open:Window->Preferences->Checkstyle

SelectNew->"ProjectRelativeConfiguration"inthe"Type"dropdown

Givetheconfigurationanameandunderlocationput"/artemis-pom/etc/checkstyle.xml"thenhitok

YoushouldnowseeyournewconfigurationinthelistofCheckstyleprofiles.Youcanselectthenewconfigurationas

thedefaultifyouwant.

ActiveMQArtemisusesJBossLoggingandthatrequiressourcecodegenerationfromJavaannotations.Inorderforitto

'justwork'inEclipseyouneedtoinstalltheMavenIntegrationforEclipseJDTAnnotationProcessorToolkitm2e-apt.SeethisJBossblogpostfordetails.

Issue:MyJUnittestsarenotrunnablewithintheIDE.

Eclipse

Gitsetup

Schemasetup

Checkstylesetup

AnnotationPre-Processing

RunningtestsfromEclipse

Settingupannotationpre-processingintheabovesectionisallyouneedtoruntestsinthe"unit-tests"projectasthatwill

properlyaddthegeneratedloggertothesource.However,onemorestepisneededtoruntestsinotherprojectssuchas

"performance-tests"or"integration-tests"thathaveadependencyon"unit-tests".Currentlym2eclipsedoesnotproperlylink

thegeneratedsourceannotationsfolderfrom"unit-tests"whichcausestheloggerthatisgeneratedtonotbeavailable.To

simplestwaytofixthisistomanuallyaddaprojectdependencyon"unit-tests"toeachoftheprojectswhereyouwantto

runatestclassfrom:

Rightclickonthetestproject(i.e.integration-tests):Properties->JavaBuildPath->Projects->Add

Selectthe"unit-tests"projectandclickOk

Youshouldnowbeabletoruntestsassumingthattheannotationpre-processingwassetupproperlyinthepreviousstep.

EclipseIndigo(3.7)hasout-of-the-boxsupportforit.

Asofthiswriting,EclipseKepler(4.3)stilllackssupportforMaven'sjavaccplugin.Theavailablem2econnectorforjavacc-

maven-pluginrequiresadowngradeofMavencomponentstobeinstalled.manualinstallationinstructions(asofthiswriting

youneedtousethedevelopmentupdatesite).SeethispostforhowtodothiswithEclipseJuno(4.2).

ThecurrentrecommendedsolutionforEclipseKepleristomarkjavacc-maven-pluginasignoredbyEclipse,runMaven

fromthecommandlineandthenmodifytheprojectactivemq-core-clientaddingthefoldertarget/generated-

sources/javacctoitsbuildpath.

ImportingallActiveMQArtemissubprojectswillcreatetoomanyprojectsinEclipse,clutteringyourPackageExplorerandProjectExplorerviews.OnewaytoaddressthatistouseEclipse'sWorkingSetsfeature.Agoodintroductiontoitcanbe

foundataDzonearticleonEclipseWorkingSets.

M2EConnectorforJavacc-Maven-Plugin

UseProjectWorkingSets

WeuseApacheMaventobuildthecode,distribution,etc.andtomanagedependencies.

Weusegitbooktobuildthedocs.

TheminimumrequiredMavenversionis3.0.0.

NotethattherearesomecompatibilityissueswithMaven3.Xstillunsolved.Thisisspeciallytrueforthe'site'plugin.

Thefullreleaseusesgitbooktobuildastaticwebsitefromthedocumentation.ThisisautomaticallyinstalledusinganNPM

pluginandiscontrolledviaapackage.jsonfile.

InstallNPMusingtheinstructionsbelow

cdartemis-website

alterthe`package.json`changingtheversion

npmcacheclean;rm-rf./node_modules/./nodenpm-shrinkwrap.json

npminstall--save-dev

npmshrinkwrap--dev

Thenewnpm-shrinkwrap.jsonshouldbewritten,commitit.

Artemiswillautomatetheexecutionanddownloadofnpm.Butitmaybeusefultoinstallitonyoursystem.Simplytype:

$npminstall-ggitbook-cli

Ifyoudon'thavenpminstalledthenyouwouldneedtoinstallitfirst.

$yuminstallnpm

ThisiswhatyoushoulddoifyouareusingFedora24+.

$dnfinstallnodejs

Theeasiestwaywouldbethroughbrewbrew

Youfirstinstallbrewusingtheinstructionsonthebrewwebsite.

Building

FullRelease

Upgradingthegitbookversionandregeneratingthenpm-shrinkwrap.jsonfile

gitbook

InstallnpmOnFedora

InstallnpmOnFedora24

InstallnpmOnMac-OS

Afteryouinstalledbrewyoucaninstallnpmby:

brewinstallnpm

Tobuildthefullreleasewithdocumentation,Javadocs,andthefullwebsite:

$mvn-Preleasepackage

Toinstallittoyourlocalmavenrepo:

$mvn-Preleaseinstall

ItispossibletobuildadistributionwithoutthemanualsandJavadocs.simplyrun

$mvnpackage

Fromeitherdocs/hacking-guide/enordocs/user-manual/enrungitbookbuild(afteryou'veinstalledgitbook)

Buildthedistributionwithoutdocs

Buildingthedocs

Toruntheunittests:

$mvn-Pteststest

Generatingreportsfromunittests:

$mvninstallsite

Runningtestsindividually

$mvn-Ptests-DfailIfNoTests=false-Dtest=<test-name>test

where<test-name>isthenameoftheTestclasswithoutitspackagename

ThebrokeriscomprisedofPOJOssoit'ssimpletoconfigureandrunabrokerinstanceandtestparticularfunctionality.

Evencomplextest-casesinvolvingmultipleclusteredbrokersarerelativelyeasytowrite.Almosteverytestinthetest-suite

followsthispattern-configurebroker,startbroker,testfunctionality,stopbroker.

Thetest-suiteusesJUnittomanagetestexecutionandlife-cycle.Mosttestsextend

org.apache.activemq.artemis.tests.util.ActiveMQTestBasewhichcontainsJUnitsetupandtear-downmethodsaswellasa

wealthofutilityfunctionstoconfigure,start,manage,andstopbrokersaswellasperformothercommontasks.

Checkoutorg.apache.activemq.artemis.tests.integration.SimpleTest.It'saverysimpletest-casethatextends

org.apache.activemq.artemis.tests.util.ActiveMQTestBaseandusesitsmethodstoconfigureaserver,runatest,andthen

super.tearDown()cleansituponcethetestcompletes.Thetest-caseincludescommentstoexplaineverything.Asthe

nameimplies,thisisasimpletest-casethatdemonstratesthemostbasicfunctionalityofthetest-suite.Asimpletestlike

thistakeslessthanasecondtorunonmodernhardware.

Althoughorg.apache.activemq.artemis.tests.integration.SimpleTestissimpleitcouldbesimplerstillbyextending

org.apache.activemq.artemis.tests.util.SingleServerTestBase.Thisclassdoesallthesetupofasimpleserverautomatically

andprovidesthetest-casewithaServerLocator,ClientSessionFactory,andClientSessioninstance.

org.apache.activemq.artemis.tests.integration.SingleServerSimpleTestisanexamplebasedon

org.apache.activemq.artemis.tests.integration.SimpleTestbutextends

org.apache.activemq.artemis.tests.util.SingleServerTestBasewhicheliminatesallthesetupandclassvariableswhichare

providedbySingleServerTestBaseitself.

Animportanttaskforanytest-caseistocleanupalltheresourcesitcreateswhenitruns.Thisincludestheserverinstance

itselfandanyresourcescreatedtoconnecttoit(e.g.instancesofServerLocator,ClientSessionFactory,ClientSession,

etc.).Thistaskistypicallycompletedinthetest'stearDown()method.However,ActiveMQTestBase(andotherclasseswhich

Tests

RunningTests

WritingTests

Keysforwritinggoodtests

Avoidleaks

extendit)simplifiesthisprocess.Asorg.apache.activemq.artemis.tests.integration.SimpleTestdemonstrates,thereare

severalmethodsyoucanusewhencreatingyourtestwhichwillensurepropercleanupautomaticallywhenthetestistorndown.Theseinclude:

Alltheoverloadedorg.apache.activemq.artemis.tests.util.ActiveMQTestBase.createServer(..)methods.Ifyouchoose

nottouseoneofthesemethodstocreateyourActiveMQServerinstancethenusetheaddServer(ActiveMQServer)methodtoaddtheinstancetothetest-suite'sinternalresourceledger.

Methodsfromorg.apache.activemq.artemis.tests.util.ActiveMQTestBasetocreateaServerLocatorlike

createInVMNonHALocatorandcreateNettyNonHALocator.IfyouchoosenottouseoneofthesemethodsthenuseaddServerLocator(ServerLocator)toaddthelocatortothetest-suite'sinternalresourceledger.

org.apache.activemq.artemis.tests.util.ActiveMQTestBase.createSessionFactory(ServerLocator)forcreatingyour

sessionfactory.Ifyouchoosenottousethismethodthenuseorg.apache.activemq.artemis.tests.util.ActiveMQTestBase.addSessionFactorytoaddthefactorytothetest-suite's

internalresourceledger.

Therearenumerousmethodsinorg.apache.activemq.artemis.tests.util.ActiveMQTestBasetocreateaconfiguration.These

methodsarenamedlikecreate*Config(..).Eachonecreatesaslightlydifferentconfigurationbutthereisalotofoverlap

betweenthem.

Inanycase,org.apache.activemq.artemis.core.config.Configurationisafluentinterfacesoit'seasytocustomizehoweveryouneed.

Ifyouneedideasonhowtoconfiguresomethingortestsomethingtrylookingthroughthetest-suiteatothertest-cases

whichmaybesimilar.Thisisoneofthebestwaystolearnhowthetest-suiteworksandhowyoucanleveragethetesting

infrastructuretotestyourparticularcase.

Createconfigurations

Lookatothertest-cases

Eclipsecodeformattingand(basic)projectconfigurationfilescanbefoundattheetc/folder.Youshouldmanuallycopy

themafterimportingallyourprojects:

forsettings_dirin`find.-typed-name.settings`;do

\cp-vetc/ide-settings/eclipse/org.eclipse.jdt.*$settings_dir

done

Donotusethemaven-eclipse-plugintocopythefilesasitconflictswithm2e.

Ifyoucompletedthestepdescribedonideainstructions,andselectedthecodestyleaccordinglyyoushouldbereadyto

go.

ForeditorssupportingEditorConfig,asettingsfileisprovidedinetc/ide-settings/editorconfig.ini.CopyittoyourArtemistop

leveldirectoryandnameit.editorconfig

CodeFormatting

Eclipse

IDEA

EditorConfig

Whenareleaseisproposedamavenrepositoryisstaged.

ThisinformationwasextractedfromGuidetoTestingStagedReleases

Forexamples,the1.1.0releasehadtheMavenRepositorystatgedas

https://repository.apache.org/content/repositories/orgapacheactivemq-1066.

Thefirstthingyouneedtodoistobeabletousethisrelease.Theeasiestwaywehavefoundistochangeyourmaven

settingsat~/.m2/settings.xml,settingupthestagedrepo.

file~/.m2/settings.xml:

<?xmlversion="1.0"encoding="UTF-8"standalone="no"?>

<settings>

<profiles>

<profile>

<id>apache-artemis-test</id>

<repositories>

<repository>

<id>artemis-test</id>

<name>ApacheArtemisTest</name>

<url>https://repository.apache.org/content/repositories/orgapacheactivemq-1066</url>

<layout>default</layout>

<releases>

<enabled>true</enabled>

</releases>

<snapshots>

<enabled>true</enabled>

</snapshots>

</repository>

</repositories>

<pluginRepositories>

<pluginRepository>

<id>artemis-test2</id>

<name>ApacheArtemisTest</name>

<url>https://repository.apache.org/content/repositories/orgapacheactivemq-1066</url>

<releases>

<enabled>true</enabled>

</releases>

<snapshots>

<enabled>true</enabled>

</snapshots>

</pluginRepository>

</pluginRepositories>

</profile>

</profiles>

<activeProfiles>

<activeProfile>apache-artemis-test</activeProfile>

</activeProfiles>

</settings>

Afteryouconfigurethis,allthemavenobjectswillbeavailabletoyourbuilds.

TheApacheActiveMQArtemisexampleswillcreateserversandusemostofthemavencomponentsasrealapplication

weresupposedtodo.Youcandothisbyrunningtheseexamplesafterthe.m2profileinstallationsforthestagedrepository.

Validatingreleases

Settingupthemavenrepository

Usingtheexamples

Ofcourseyoucanuseyourownapplicationsafteryouhavestagedthemavenrepository.

CoreActiveMQArtemismembershavewriteaccesstotheApacheActiveMQArtemisrepositoriesandwillberesponsible

foracknowledgingandpushingcommitscontributedviapullrequestsonGitHub.

CoreActiveMQArtemismembersarealsoabletopushtheirowncommitsdirectlytothecanonicalApacherepository.

However,theexpectationhereisthatthedeveloperhasmadeagoodefforttotesttheirchangesandisreasonably

confidentthatthechangesthatarebeingcommittedwillnotbreakthebuild.

Whatdoesitmeantobereasonablyconfident?Ifthedeveloperhasrunthesamemavencommandsthatthepull-request

buildsarerunningtheycanbereasonablyconfident.CurrentlythePRbuildrunsthiscommand:

mvn-Pfast-tests-Pextra-testsinstall

However,ifthechangesaresignificant,touchesawideareaofcode,orevenifthedeveloperjustwantsasecondopinion

theyareencouragedtoengageothermembersofthecommunitytoobtainanadditionalreviewpriortopushing.Thiscan

easilybedoneviaapullrequestonGitHub,apatchfileattachedtoanemailorJIRA,committoabranchintheApachegit

repo,etc.Havingadditionaleyeslookingatsignificantchangespriortocommittingtothemaindevelopmentbranchesis

definitelyencouragedifithelpsobtainthe"reasonableconfidence"thatthebuildisnotbrokenandcodequalityhasnot

decreased.

Ifthebuilddoesbreakthendeveloperisexpectedtomaketheirbestefforttogetthebuildsfixedinareasonableamountof

time.Ifitcannotbefixedinareasonableamountoftimethecommitcanberevertedandre-reviewed.

DevelopersareencouragedalsotousetheDevprofile,whichwillactivatecheckstyleduringthebuild:

mvn-Pdevinstall

Pleaseensurethecommitmessagesfollowthe50/72formatasdescribedhere.Thisformatfollowstherecommendation

fromtheofficialGitbook.

Asidefromthetraditionaloriginandupstreamrepositoriescommitterswillneedanadditionalreferenceforthecanonical

Apachegitrepositorywheretheywillbemergingandpushingpull-requests.Forthepurposesofthisdocument,let's

assumetheseref/repoassociationsalreadyexistasdescribedintheWorkingwiththeCodesection:

origin:https://github.com/(your-user-name)/activemq-artemis.git

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

AddthecanonicalApacherepositoryasaremote.Herewecallitapache.

$gitremoteaddapachehttps://git-wip-us.apache.org/repos/asf/activemq-artemis.git

Addthefollowingsectiontoyour/.git/configstatementtofetchallpullrequestssenttotheGitHubmirror.Weareusing

NotesforMaintainers

Usingthedevprofile.

CommitMessages

Configuringgitrepositories

upstreamastheremotereponame(asnotedabove),buttheremotereponamemaybedifferentifyouchoose.Just

besuretoeditallreferencestotheremotereponamesoit'sconsistent.

[remote"upstream"]

url=git@github.com:apache/activemq-artemis.git

fetch=+refs/heads/*:refs/remotes/upstream/*

fetch=+refs/pull/*/head:refs/remotes/upstream/pr/*

Herearethebasiccommandstoretrievepullrequests,merge,andpushthemtothecanonicalApacherepository:

1. Downloadalltheremotebranchesetc...includingallthepullrequests.

$gitfetch--all

Fetchingorigin

Fetchingupstream

remote:Countingobjects:566,done.

remote:Compressingobjects:100%(188/188),done.

remote:Total566(delta64),reused17(delta17),pack-reused351

Receivingobjects:100%(566/566),300.67KiB|0bytes/s,done.

Resolvingdeltas:100%(78/78),done.

Fromgithub.com:apache/activemq-artemis

*[newref]refs/pull/105/head->upstream/pr/105

2. Checkoutthepullrequestyouwishtoreview

$gitcheckoutpr/105-B105

3. Rebasethebranchagainstmaster,sothemergewouldhappenatthetopofthecurrentmaster

$gitpull--rebaseapachemaster

4. Onceyou'vereviewedthechangeandarereadytomergecheckoutmaster.

$gitcheckoutmaster

5. Ensureyouareuptodateonyourmasteralso.

$gitpull--rebaseapachemaster

6. Weactuallyrecommendcheckingoutmasteragain,tomakesureyouwouldn'taddanyextracommitsbyaccident:

$gitfetchapache

$gitcheckoutapache/master-Bmaster

7. Createanewmergecommitfromthepull-request.IMPORTANT:Thecommitmessagehereshouldbesomethinglike:

"Thiscloses#105"where"105"isthepullrequestID.The"#105"showsupasalinkintheGitHubUIfornavigatingto

thePRfromthecommitmessage.ThiswillensurethegithubpullrequestisclosedevenifthecommitIDchangeddue

toeventualrebases.

Mergingandpushingpullrequests

$gitmerge--no-ff105-m"Thiscloses#105"

8. PushtothecanonicalApacherepo.

$gitpushapachemaster

Ifyoufollowedthenamingconventionsdescribedhereyoucanusethescripts/rebase-PR.shscripttoautomatethe

mergingprocess.Thiswillexecutetheexactstepsdescribedonthisprevioussection.

Simplyuse:

$<checkout-directory>/scripts/merge-pr.sh<PRnumber>MessageonthePR

Example:

$pwd

/checkouts/apache-activemq-artemis

$./scripts/merge-PR.sh175ARTEMIS-229addressonSecurityInterface

Thepreviousexamplewastakenfromarealcasethatgeneratedthismergecommiton#175.

AfterthisyoucanpushtothecanonicalApacherepo.

$gitpushapachemaster

Itisrecommendedthatyouworkawayfrommasterfortworeasons:

1. WhenyousendaPR,yourPRbranchcouldberebasedduringtheprocessandyourcommitIDchanged.Youmight

getunexpectedconflictswhilerebasingyouroldbranch.

2. Youcouldenduppushingthingsupstreamthatyoudidn'tintendto.Minimizeyourrisksbyworkingonabranchaway

frommaster.

TheGitHubmirrorrepository(i.e.upstream)iscloningthecanonicalApacherepository.Becauseofthistheremaybea

slightdelaybetweenwhenacommitispushedtotheApacherepoandwhenthatcommitisreflectedintheGitHubmirror.

ThismaycausesomedifficultywhentryingtopushaPRtoapachethathasbeenmergedontheout-of-dateGitHubmirror.

Youcanwaitforthemirrortoupdatebeforeperformingthestepsaboveoryoucanchangeyourlocalmasterbranchto

trackthemasterbranchonthecanonicalApacherepositoryratherthanthemasterbranchontheGitHubmirror:

$gitbranchmaster-uapache/master

WhereapachepointstothecanonicalApacherepository.

Usingtheautomatedscript

Useaseparatebranchforyourchanges

Notes:

Ifyou'dlikeyourlocalmasterbranchtoalwaystrackupstream/master(i.e.theGitHubmirror)thenanotherwaytoachieve

thisistoaddanotherbranchthattracksapache/masterandpushfromthatbranche.g.

$gitcheckoutmaster

$gitbranchapache_master--trackapache/master

$gitpull

$gitmerge--no-ffpr/105

$gitpush

TheApacheActiveMQArtemisprojectwasstartedinOctober2014.TheArtemiscodebasewasseededwithacode

donationgrantedbyRedHat,oftheHornetQproject.Thecodedonationprocessconsistedoftakingasnapshotofthe

latestHornetQcodebaseandcontributingthissnapshotasaninitialgitcommitintotheArtemisgitrepository.

TheHornetQcommithistoryispreservedandcanbeaccessedhere:https://github.com/hornetq/hornetq/tree/apache-

donation

CreditshouldbegiventothosedeveloperswhocontributedtotheHornetQproject.Thetop10committersarehighlighted

here:

ClebertSuconic

TimFox

FranciscoBorges

AndyTaylor

JeffMesnil

OvidiuFeodorov

HowardGao

JustinBertram

TrustinLee

AdrianBrock

FormoreinformationpleasevisittheHornetQGitHubproject.

Itmaybeusefultolookatthedonationhistorycombinedwiththeartemishistory.Itisthecasewheneventuallylookingat

oldchanges.

Forthatthereisascriptthatwillrebasemasteragainstthedonationbranchundermaster/scripts:

rebase-donation.sh

History

Rebasingoriginaldonation