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:
[email protected]:<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)
[email protected]:<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"]
[email protected]: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
Top Related