table of contents - apache activemq · 2. pushing pulled updates (or local commits if you...
TRANSCRIPT
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