Development Workflow · GitHub

Download Development Workflow · GitHub

Post on 06-Nov-2015

9 views

Category:

Documents

0 download

DESCRIPTION

Development Workflow GitHub

TRANSCRIPT

InSymPyweencouragecollaborativework.Everyoneiswelcometojoinandtoimplementnewfeature,fixsomebug,givegeneraladvice,etc.Also,wetrytodiscusseverythingandtorevieweachother'sworksothatmanyeyescanseemorethusraisingthequality.Generaldiscussiontakesplaceonsympy@googlegroups.commailinglistandintheissues.SomediscussionalsotakesplaceonIRC(ourchannelis#sympyatfreenode).Assomeofyoualreadyknow,softwaredevelopmentisnotjustcoding.Manynoncodingtaskshavetobedoneinordertoproducegoodcode.Forexample:settingupinfrastructure,designing,testing,documenting,assistingnewdevelopers(wearedoingithere),andofcourseprogramming.Butevenprogrammingisnotallaboutwritingthecode,itisaboutwritingthecodeandpreparingitsothatthecodecanbeincludedintheproject.Bothproducingthecodeandbringingittotheprojectareimportantpartsofthegamewithoutthecodethereisnothingtobringin,andhavingthecodeoutsideisanowinforanyone.Asalreadysaidabove,wereviewchanges.ThisideawasborrowedfromsuccessfulprojectslikeLinux,Python,SAGEandmanymore.Inshort,eachchangeisfirstreviewedbyotherdevelopersandonlywhenitisapprovedisthecodepushedin.Likeittakesefforttowritegoodandclearcode,reviewingother'sworkneedsefforttoo.Therearegoodpracticeshowtodothissothatreviewingisfunforboththeauthorandthereviewer.Wetrytofollowthesegoodpractices,andwe'lltrytoshowyouhowtofollowthemtoo.Whenreviewingother'spatchesyoulearnalot,sowhynotparticipateasareviewertoo?Anyoneregardlessoftechnicalskillcanhelpreviewcode,andit'sanexcellentwayfornewcomerstolearnaboutSympy'sdevelopmentprocessandcommunity.License:NewBSDLicense(seetheLICENSEfilefordetails)coversallfilesintheSymPyrepositoryunlessstatedotherwise.Thereareafewwaystocreateandsendapatch.ThebestwayistosendaGitHubpullrequestagainstthesympy/sympyrepository.We'llreviewitandpushitin.TheGitHubpullrequestisthepreferredmethod,becauseitmakesiteasyforustoreviewandpushthecodein.Morequickly,butnotconvenientforreviewingandmerging,istocreateapatchfileusinggitalone.Thiswaycanbeusedifthepatchhasahighpriorityorissignificant,onlyoneortwofilesareinvolved,oryoudon'thaveenoughtimetousethepreferredmethod.AlthoughwearegratefulforanyimprovementsofSympy,westronglyrecommendyousubmityourpatchesaspullrequests:thiswillgreatlyspeeduptheprocessingofthepatchandensurethatitdoesn'tgetforgottenduetoinactivity.Thebasicworkflowforbothvariantsisafollows:1. Createyourenvironment,ifitwasnotcreatedearlier.2. Createanewbranch.DevelopmentworkflowIntroductionHowtosendapatch3. Modifycodeand/orcreatetestsofit.4. BesurethatalltestsofSymPypass.5. Onlythencommitchanges.6. Createpatchfile,orpullrequestfromGitHub.AllthosearedescribedinthedetailsbelowWorkflowprocess,butbeforeyoureadthat,itwouldbeusefultoacquaintyourselfwithCodingconventionsinSympy.Ifyouhaveanyquestionsyoucanaskthemonthemailinglist.FollowthestandardStyleGuideforPythonCodewhenwritingcodeforSymPy,asexplainedatthefollowingURLs:http://www.python.org/dev/peps/pep0008http://www.python.org/dev/peps/pep0257Inparticular,Use4spacesforindentationlevels.Usealllowercasefunctionnameswithwordsseparatedbyunderscores.Forexample,youareencouragedtowritePythonfunctionsusingthenamingconventiondefset_some_value()insteadoftheCamelCaseconvention.UseCamelCaseforclassnamesandmajorfunctionsthatcreateobjects,e.g.classPolynomialRing(object)Note,however,thatsomefunctionsdohaveuppercaseletterswhereitmakessense.Forexample,formatricestheyareLUdecompositionorT(transposition)methods.prime'sdocstringisanexampleofawellformatteddocstring:"""Returnthenthprime.Primesareindexedasprime(1)=2,prime(2)=3,etc....Thenthprimeisapproximatelyn*log(n)andcanneverbelargerthan2**n.SeeAlso========sympy.ntheory.primetest.isprime,primerange,primepiReferences==========..[1]http://primes.utm.edu/glossary/xpage/BertrandsPostulate.htmlExamples========>>>fromsympyimportprime>>>prime(10)29>>>prime(1)2"""CodingconventionsinSympyStandardPythoncodingconventionsDocumentationstringsFormoreinformationseeWritingdocumentationarticleonwiki.SymPyusesasinglecodebaseforPython2andPython3(thecurrentsupportedversionsarePython2.6,2.7,3.2,and3.3).ThismeansthatyourcodeneedstoruninbothPython2andPython3.Tomakethiseasier,therearemanyfunctionsinsympy.core.compatibilitythatshouldbeusedwhentherearedifferencesbetweenthetwoPythonversions.Toseewhatthingsyoucanimportfromthatfile,lookatitssource.IfyouneedtouseadditionalfunctionsormethodsthatchangenamesfromPython2toPython3,itisfarbettertoaddtosympy.core.compatibilityandimportfromtherethantobloatindividualsourcefileswithversionspecificlogic.Ingeneral,thePython3namesaretobepreferred,butthisisnotanabsoluterequirement.Forexample,thecurrentcodebaseusesxrangeextensively.Youshouldalsomakesurethatyouhave:from__future__importprint_function,divisionatthetopofeachfile.Thiswillmakesurethatprintisafunction,andthat1/2doesfloatingpointdivisionandnotintegerdivision.Youshouldalsobeawarethatallimportsareabsolute,soimportmodulewillnotworkifmoduleisamoduleinthesamedirectoryasyourfile.Youwillneedtouseimport.module.Creatingofenvironmentisonceonly.SymPyhasaharddependencyonthempmathlibrary(version>=0.19).Youshouldinstallitfirst,pleaserefertothempmathinstallationguide.ToinstallgitinLinuxlikesystemsyoucandoitviayournativepackagemanagementsystem:$yuminstallgitor:$sudoaptgetinstallgitInWindowssystems,firstofall,installPythonfrom:http://python.org/download/bydownloadingthe"Python2.7Windowsinstaller"(orPython2.6or2.5)andrunningit.ThendonotforgettoaddPythontothe$PATHenvironment.OnWindowsandMacOSX,theeasiestwaytogetgitistodownloadGitHub'ssoftware,whichwillinstallgit,andalsoprovideaniceGUI(thistutorialwillbebasedonthePython3WorkflowprocessCreateyourenvironmentInstallmpmathInstallgitcommandlineinterface).Note,youmayneedtogointotheGitHubpreferencesandchoosethe"InstallCommandLineTools"optiontogetgitinstalledintotheterminal.IfyoudodecidetousetheGitHubGUI,youshouldmakesurethatany"syncdoesrebase"optionisdisabledinthesettings.SympydevelopmentusesafewtoolsthatarenotincludedinabasicPythondistribution.Youwon'treallyneedthemuntilyouaregettingreadytosubmitapullrequest,buttosavetimelater,youcaninstall:Sphinxdocumentationgenerator(packagesphinxdoconDebianbasedsystems)Pythoncoveragelibrary(packagepythoncoverage)Programsneededforbuildingdocs,suchasrsvgconvert.Anuptodatelistisismaintainedindoc/README.rstGittrackswhomakeseachcommitbycheckingtheusersnameandemail.Inaddition,weusethisinfotoassociateyourcommitswithyourGitHubaccount.Tosetthese,enterthecodebelow,replacingthenameandemailwithyourown(globalisoptional).:$gitconfigglobaluser.name"FirstnameLastname"$gitconfigglobaluser.email"your_email@youremail.com"Thenameshouldbeyouractualname,notyourGitHubusername.Theseglobaloptions(i.e.applyingtoallrepositories)areplacedin~/.gitconfig.Youcaneditthisfiletoaddsetupcolorsandsomehandyshortcuts:[user]name=FirstnameLastnameemail=your_email@youremail.com[color]diff=autostatus=autobranch=autointeractive=true[alias]ci=commitdi=diffcolorwordsst=statusco=checkoutlog1=logpretty=onelineabbrevcommitlogs=logstatItcanbeconvenientinfuturetotunethebashprompttodisplaythecurrentgitbranch.Theeasiestwaytodoit,istoaddthesnippetbelowtoyour.bashrcor.bash_profile:PS1="[\u@\h\W\$(gitbranch2>/dev/null|grepe'\*'|sed's/^..\(.*\)/{\1}/')]\$"Butbetteristousegitcompletionfromthegitsource.Thisalsohastheadvantageofaddingtabcompletiontojustabouteverygitcommand.Italsoincludesmanyotherusefulfeatures,forexample,promptings.Tousegitcompletion,firstdownloadthegitsourcecode(about27MiB),thencopythefiletoyourprofiledirectory:InstallothersoftwareBasicgitsettingsAdvancedtuning$gitclonegit://git.kernel.org/pub/scm/git/git.git$cpgit/contrib/completion/gitcompletion.bash~/.gitcompletion.shReadinstructionsin'~/.gitcompletion.sh'NotethatifyouinstallgitfromthepackagemanagerinmanyLinuxdistros,thisfileisalreadyinstalledforyou.Youcancheckifitisinstalledbyseeingiftabcompletionworksongitcommands(try,e.g.,gitcommi,orgitlogst).YoucanalsocheckifthePS1commandsworkbydoingsomethinglike:$PS1='\W$(__git_ps1"%s")\$'Andyourcommandpromptshouldchangetosomethinglike:sympymaster$Note,itisimportanttodefineyourPS1usingsinglequotes('),notdoublequotes("),orelsebashwillnotupdatethebranchname.AsyouaregoingtouseGitHubyoushouldhaveaGitHubaccount.Ifyouhavenotoneyetthensignupat:https://github.com/signup/freeThencreateyourownforkoftheSymPyproject(ifyouhavenotyet).GototheSymPyGitHubrepository:https://github.com/sympy/sympyandclicktheForkbutton.NowyouhaveyourownrepositoryfortheSymPyproject.IfyourusernameinGitHubismynickthentheaddressoftheforkedprojectwilllooksomethinglike:https://github.com/mynick/sympySometoolsconnecttoGitHubwithoutSSH.TousethesetoolsproperlyyouneedtofindandconfigureyourAPIToken.OnGitHub,clickAccountSettingsthenAccountAdmin.CreateGitHubaccountEnterthecodebelow,replacingthemynickand012apitokenwithyourown:$gitconfigglobalgithub.usermynick$gitconfigglobalgithub.token012apitokenNote:ifyoueverchangeyourGitHubpassword,anewtokenwillbecreatedandwillneedtobeupdated.Note:GitHubnolongerusesAPItokens.Youcanskipthisstep.OnyourmachinebrowsetowhereyouwouldliketostoreSymPy,andclone(download)thelatestcodefromSymPy'soriginalrepository(about20MiB):$gitclonegit://github.com/sympy/sympy.git$cdsympyThenassignyourreadandwriterepotoaremotecalled"github":$gitremoteaddgithubgit@github.com:mynick/sympy.gitFormoreinformationaboutGitHubforkingandtuningsee:[8],[9]and[11].ToestablishasecureconnectionbetweenyourcomputerandGitHubseedetailedinstructionsin[11].IfyouhaveanyproblemswithSSHaccesstoGitHub,readthetroubleshootinginstructionsat[12],oraskusinmaillist.Andnow,donotforgettogotothe`Createseparatedbranch`_instructionsbeforemodifyingthecode.YoumaywanttotakeadvantageofusingvirtualenvironmentstoisolateyourdevelopmentversionofSymPyfromanysystemwideinstalledversions,e.g.fromaptgetinstallpythonsympy.Therearetwoleadingvirtualenvironmenttools,virtualenvandconda.Condahastheadvantagethatallsoftwareinstallsarebinaryandthatyoucaneasilyswitchbetweenpythonversions.Hereisanexampleofusingcondatocreatetwodevelopmentvirtualenvironments,oneforpython2.7andoneforpython3.4:$condacreatensympydevpy27python=2.7mpmath>=0.19$condacreatensympydevpy34python=3.4mpmath>=0.19YounowhavetwoenvironmentsthatyoucanusefortestingyourdevelopmentcopyofSymPy.Forexample,cloneyourSymPyforkfromGithub:$gitclonegit@github.com:/sympy.gitCloningSymPySetupSSHkeysVirtualEnvironments$cdsympyNowactivatethePython2.7environment:$sourceactivatesympydevpy27NotethatonWindowssourceisnotrequiredinthecommand.AndruntheSymPytests:(sympydevpy27)$bin/testAfterthetestsrun,thentrythetestsinthePython3.4environment:(sympydevpy27)$sourcedeactivate$sourceactivatesympydevpy34(sympydevpy34)$bin/testYoucanalsoinstallSymPyintotheenvironmentifyouwish(soyoucanusethedevelopmentversionfromanylocationonyourfilesystem):(sympydevpy34)$pythonsetup.pyinstallIfyouprefervirtualenv,theprocessissimilar,excepttheswitchbetweenPython2and3isn'tassimple.Typically,youwillcreateanewbranchtobeginworkonanewissue.Alsopullrequestrelatedwiththem.Abranchnameshouldbrieflydescribethetopicofthepatchorpullrequest.Ifyouknowtheissuenumber,thenthebranchnamecouldbe,forexample,1234_sequences.Tocreateandcheckout(thatis,makeittheworkingbranch)anewbranch$gitbranch1234_sequences$gitcheckout1234_sequencesorinonecommandusing$gitcheckoutb1234_sequencesToviewallbranches,withyourcurrentbranchhighlighted,type:$gitbranchAndremember,nevertypethefollowingcommandsinmaster:gitmerge,gitcommit,gitrebase....Donotforgetthatallnewfunctionalityshouldbetested,andallnewmethods,functions,andclassesshouldhavedoctestsshowinghowtousethem.Keepinmind,doctestsarenottests.Thinkofthemasexamplesthathappentobetested.Somekeydifferences:writedocteststobeinformativewriteregularteststocheckforregressionsandCreateaseparatebranchCodemodificationcornercases.doctestscanbechangedatanytimeregulartestsshouldnotbechanged.Inparticular,weshouldbeabletochangeordeleteanydoctestatanytimeifitmakesthedocstringbettertounderstand.Toensureeverythingstaysinshape,letsseeifalltestspass:$./bin/test$./bin/doctestEachcommandwillshowaDONOTCOMMITmessageifanyofthetestsitrunsdoesnotpass.bin/testandbin/doctestdofasttests(thosethattakeseconds).You'llwanttorunthemwheneveryourcodeissupposedtoworkandnotbreakanything.Youcanalsorunbin/testslow,toruntheslowtests(thosethatmaytakeminuteseach).Codequality(unwantedspacesandindents)arecheckedby./bin/testutilitiestoo.Butyoucanseparatelyrunthistestwiththehelpofthiscommand:$./bin/testqualityIfyouhavetrailingwhitespaceitwillshowerrors.Thisonewillfixunwantedspaces.$./bin/strip_whitespaceIfyouwanttotestonlyonesetofteststry:$./bin/testsympy/concrete/tests/test_products.pyButrememberthatalltestsshouldpassbeforecommitting.NotethatalltestswillberunwhenyoumakeyourpullrequestautomaticallybyTravisCI,sodonotworrytoomuchaboutrunningeverypossibletest.Youcanusuallyjustrun:$./bin/testmod$./bin/doctestmodwheremodisthenameofthemodulethatyoumodified.Youcancheckwhatfilesarechanged:$gitstatusAddnewfilestotheindexifnecessary:$gitaddnew_file.pyChecktotalchanges:$gitdiffBesurethatalltestsofSymPypassCommitthechangesYouarereadytocommitchangeslocally.Acommitalsocontainsacommitmessagewhichdescribesit.Seethenextsectionforguidelinesonwritinggoodcommitmessages.Type:$gitcommitAneditorwindowwillappearautomaticallyinthiscase.InLinux,thisisvimbydefault.Youcanchangewhateditorpopsupbychangingthe$EDITORshellvariable.Alsowiththehelpofoptionayoucantellthecommandcommittoautomaticallystagefilesthathavebeenmodifiedanddeleted,butnewfilesyouhavenottoldgitaboutwillnotbeaffected,e.g.,:$gitcommitaIfyouwanttostageonlypartofyourchanges,youcanusetheinteractivecommitfeature.Justtype:$gitcommitinteractiveandchoosethechangesyouwantintheresultinginterface.ThereareonlytwoformattingrulesforcommitmessagesThereshouldbeasinglelinesummaryof71charactersorlesswhichallowstheonelineformofthelogtodisplaythesummarywithoutwrapping.Acommonconventionistonotendthesummarywitha..Additionaldetailscanbegivenafterthesummary.Makesuretoleaveablanklineafterthesummaryandtokeepalllinesto78charactersorlesssotheycanbeeasilybereadinterminalswhichdon'tautomaticallywraplines.Hereisanexamplecommitmessage(fromthecommit[bf0e81e12a2f75711c30f0788daf4e58f72b2a41],whichispartoftheSymPyhistory):integrals:Improvedspeedofheurisch()andrevisedtestsImprovedspeedofantiderivativecandidateexpansionandsolutionphasesusingexplicitdomainsandsolve_lin_sys().Theupsideofthischangeisthatlargeintegrals(thosethatgeneratelotsofmonomials)arenowcomputed*much*faster.ThedownsideisthatintegralsinvolvingDerivative()don'tworkanymore.I'mnotsureiftheyreallyusedtoworkproperlyoritwasjustacoincidenceand/orbadimplementation.Thisneedsfurtherinvestigation.Example:In[1]:fromsympy.integrals.heurischimportheurischIn[2]:f=(1+x+x*exp(x))*(x+log(x)+exp(x)1)/(x+log(x)+exp(x))**2/xIn[3]:%timeratsimp(heurisch(f,x))CPUtimes:user7.27s,sys:0.04s,total:7.31sWalltime:7.32sOut[3]:2x2xx2logx+2x+2xlog(x)++2log(x)+log(x)1+2xx++log(x)WritingcommitmessagesPreviouslyittook450secondsand4GBofRAMtocompute.Somethingstonoteaboutthiscommitmessage:Thefirstlinegivesabriefdescriptionofwhatthecommitdoes.ToolslikegitshortlogorevenGitHubonlyshowthefirstlineofthecommitbydefault,soitisimportanttoconveythemostimportantaspectsofthecommitinthefirstline.Thefirstlinehasintegrals:,whichgivescontexttothecommit.Acommitwon'talwaysbeseeninthecontextofyourbranch,soitisoftenhelpfultogiveeachcommitsomecontext.Thisisnotrequired,though,asitisnothardtolookatthecommitmetadatatoseewhatfilesweremodifiedoratthecommithistorytoseethenearbyrelatedcommits.Afterthefirstline,thereisaparagraphdescribingthecommitinmoredetail.Thisisimportant,asitdescribeswhatthecommitdoes,whichmightbehardtofigureoutjustfromlookingatthediff.Italsogivesinformationthatmightnotbeinthediffatall,suchasknownissues.SuchparagraphsshouldbewritteninplainEnglish.Commitmessagesareintendedforhumanreaders,bothforpeoplewhowillbereviewingyourcoderightnow,andforpeoplewhomightcomeacrossyourcommitinthefuturewhileresearchingsomechangeinthecode.Sometimes,bulletlistsareagoodformattoconveythechangesofacommit.Last,thereisanexample.Itisnicetogiveaconcreteexampleincommitsthataddnewfeatures.Thisparticularexampleisaboutimprovingthespeedofsomething,sotheexampleisabenchmarkresult.NotethatyoumayfeelfreetouseUnicodecharactersincommitmessages,suchasoutputfromtheSymPyUnicodeprettyprinter.Trytoavoidshortcommitmessages,like"Fix",andcommitmessagesthatgivenocontext,like"Foundthebug".Whenindoubt,alongercommitmessageisprobablybetterthanashortone.Besurethatyouareinyourownbranch,andrun:$gitpushgithub1234_sequencesThiswillsendyourlocalchangestoyourforkoftheSymPyrepository.Thennavigatetoyourrepositorywiththechangesyouwantsomeoneelsetopull:https://github.com/mynick/sympySelectbranch,andpressthePullRequestbutton.AfterpressingthePullRequestbutton,youarepresentedwithapreviewpagewhereyoucanenteratitleandoptionaldescription,seeexactlywhatcommitswillbeincludedwhenthepullrequestissent,andalsoseewhothepullrequestwillbesentto:CreateapatchfileorpullrequestforGitHubIfyouresendingfromatopicbranch,thetitleisprefilledbasedonthenameofthebranch.Markdownissupportedinthedescription,soyoucanembedimagesorusepreformattedtextblocks.YoucanswitchtotheCommitstabtoensurethatthecorrectsetofchangesisbeingsent.AndreviewthediffofallchangesbyswitchingtotheFilesChanged.Enterabrieftitleandinthedescriptionrefertotheissueaddressedoranyrelatedissuesusingreferenceslike"#1234"thosereferencesautomaticallycreatelinksthathelpinthereviewofthepullrequest.Ifthereisn'tanissue,oneshouldbecreatedsoevenifthepullrequestgetsclosedthereisareferencetoitintheissues.Ifpossible,refertotheissuenumberinsuchaway,e.g."fixes#1234",thattheissuegetsclosedwhenthepullrequestgetscommitted.Onceyouveenteredthetitleanddescription,customizedthecommitrange,andreviewedthecommitsandfilechangestobesent,presstheSendpullrequestbutton.Thepullrequestissentimmediately.Youretakentothemainpullrequestdiscussionandreviewpage.Additionally,allrepositorycollaboratorsandfollowerswillseeaneventintheirdashboard.hThat'sall.SeealsoUpdatingyourpullrequestIfafteratimeyouneedtomakechangesinpullrequestthenthebestwayistoaddanewcommitinyoulocalrepositoryandsimplyrepeatpushcommand:$gitcommit$gitpushgithub1234_sequencesNotethatifyoudoanyrebasingorinanywayedityourcommithistory,youwillhavetoaddthef(force)optiontothepushcommandforittowork:$gitpushfgithubYoudon'tneedtodothisifyoumerge,whichistherecommendedway.UpdatingyourpullrequestSometimes,youmayneedtomergeyourbranchwiththeupstreammaster.Usuallyyoudon'tneedtodothis,butyoumayneedtoifSomeonetellsyouthatyourbranchneedstobemergedbecausetherearemergeconflicts.sympybottellsyouthatyourbranchcouldnotbemerged.Youneedsomechangefrommasterthatwasmadeafteryoustartedyourbranch.Note,thataftercloningarepository,ithasadefaultremotecalledoriginthatpointstothesympy/sympyrepository.Andyourforkremotenamedasgithub.Youcanobservetheremotesnameswiththehelpofthiscommand:$gitremotevgithubgit@github.com:mynick/sympy.git(fetch)githubgit@github.com:mynick/sympy.git(push)origingit://github.com/sympy/sympy.git(fetch)origingit://github.com/sympy/sympy.git(push)Asanexample,considerthatwehavethesecommitsinthemasterbranchoflocalgitrepository:ABCmasterThenwehavedivergentbranch1234_sequences:ABCmaster\ab1234_sequencesInthemeantimetheremotesympy/sympymasterrepositorywasupdatedtoo:ABCDorigin/masterABCmaster\ab1234_sequencesTherearebasicallytwowaystogetuptodatewithachangedmaster:rebasingandmerging.Mergingisrecommended.Mergingcreatesaspecialcommit,calleda"mergecommit",thatjoinsyourbranchandmastertogether:ABCDorigin/master\\\Mmerge\/ab1234_sequencesNotethatthecommitsA,B,C,andDfrommasterandthecommitsaandbfrom1234_sequencesremainunchanged.Onlythenewcommit,M,isaddedto1234_sequences,whichmergesinthenewcommitbranchfrommaster.Rebasingessentiallytakesthecommitsfrom1234_sequencesandreappliesthemonthelatestmaster,sothatitisasifyouhadmadethemfromthelatestversionofthatbranchinstead.Sincethesecommitshaveadifferenthistory,theyaredifferent(theywillhavedifferentSHA1hashes,andwilloftenhavedifferentcontent):ABCDa'b'origin/masterSynchronizationwithmastersympy/sympy.Rebasingisrequiredifyouwanttoedityourcommithistory(e.g.,squashcommits,editcommitmessages,removeunnecessarycommits).Butnotethatsincethisrewriteshistory,itispossibletolosedatathisway,anditmakesitharderforpeoplereviewingyourcode,becausetheycannolongerjustlookatthe"newcommits"theyhavetolookateverythingagain,becauseallthecommitsareeffectivelynew.Thereareseveraladvantagestomerginginsteadofrebasing.Rebasingreapplieseachcommititerativelyovermaster,andifthestateofthefileschangedbythatcommitisdifferentfromwhenitwasoriginallymade,thecommitwillchange.Thismeanswhatyoucanendupgettingcommitsthatarebroken,orcommitsthatdonotdowhattheysaytheydo(becausethechangeshavebeen"rebasedout").Thiscanleadtoconfusionifsomeoneinthefuturetriestotestsomethingbycheckingoutcommitsfromthehistory.Finally,mergeconflictresolutionscanbemoredifficultwithrebasing,becauseyouhavetoresolvetheconflictsforeachindividualcommit.Withmerging,youonlyhavetoresolvetheconflictsbetweenthebranches,notthecommits.Itisquitecommonforamergetonothaveanyconflictsbutforarebasetohaveseveral,becausetheconflictsare"alreadyresolved"bylatercommits.Mergingkeepseverythingintact.Thecommitsyoumakeareexactlythesame,downtotheSHA1hash,whichmeansthatifyoucheckoutacommitfromamergedbranch,itisexactlythesameascheckingitoutfromanonmergedbranch.Whatitdoesinsteadiscreateasinglecommit,themergecommit,thatmakesitsothatthehistoryisbothmasterandyourbranch.Thiscommitcontainsallmergeconflictresolutioninformation,whichisanotheradvantageoverrebasing(allmergeconflictresolutionswhenrebasingare"sifted"intothecommitsthatcausedthem,makingtheminvisible).Sincethisguideisaimedatnewgitusers,youshouldbelearninghowtomerge.Firstmergeyourlocalrepositorywiththeremote:$gitcheckoutmaster$gitpullThisresultsin:ABCDmaster\ab1234_sequencesThenmergeyour1234_sequencesbranchfrom1234_sequences:$gitcheckout1234_sequences$gitmergemasterIfthelastcommandtellsyouthatconflictsmustbesolvedforafewindicatedfiles.Ifthat'sthecasethenthemarks>>>andandSotheresultwillbelikethat(automaticmergingc):ABCDmaster\\abM1234_sequencesNote:mergingisrecommendedoverrebasing.Thefinalaim,thatwewanttoobtainis:ABCDmaster\ab1234_sequencesThewaytodoitisfirstofalltomergelocalrepositorywiththeremotesympy/sympy:$gitcheckoutmaster$gitpullSoweobtain:ABCDmaster\ab1234_sequencesThen:$gitcheckout1234_sequences$gitrebasemasterNotethatthislastonewillrequireyoutofixsomemergeconflictsiftherearechangestothesamefileinmasterand1234_sequences.Openthefilethatittellsyouiswrong,fixthecodewith>>>and925d88fxsequencesbaseimplementation.Thenrunrebasecommandininteractivemode:$gitrebaseinteractive925d88fxOryoucanuseotherwaystopointtocommits,e.g.`gitrebaseinteractiveHEAD^^`or`gitrebaseinteractiveHEAD~2`.Aneweditorwindowwillappear(notethatorderisreversedwithrespecttothegitlogcommand):pick4d6137bsomeadditionalcorrections.pick7bbbc06bugsfixing#Rebase925d88f..7bbbc06onto925d88f##Commands:#p,pick=usecommit#r,reword=usecommit,buteditthecommitmessage#e,edit=usecommit,butstopforamending#s,squash=usecommit,butmeldintopreviouscommit#f,fixup=like"squash",butdiscardthiscommit'slogmessageToeditacommitmessage,changepicktoreword(oronoldversionsofgit,toedit)forthosethatyouwanttoeditandsavethatfile.Tosquashtwocommitstogether,changepicktosquash.Toremoveacommit,justdeletethelinewiththecommit.Toeditacommit,changepicktoedit.Afterthat,gitwilldropyoubackintoyoureditorforeverycommityouwanttoreword,andintotheshellforeverycommityouwantedtoedit:$(Changethecommitinanywayyoulike.)$gitcommitamendm"yournewmessage"$gitrebasecontinueForcommitsthatyouwanttoedit,itwillstop.Youcanthendo:$gitresetmixedHEAD^Thiswill"uncommit"allthechangesfromthecommit.Youcanthenrecommitthemhoweveryouwant.Whenyouaredone,remembertodo:$gitrebasecontinueMostofthissequencewillbeexplainedtoyoubytheoutputofthevariouscommandsofgit.Continueuntilitsays:Successfullyrebasedandupdatedrefs/heads/master.Ifatanypointyouwanttoaborttherebase,do:$gitrebaseabortWarning:thiswillrungitresethard,deletinganyuncommittedchangesyouhave.Ifyouwanttosaveyouruncommittedchanges,rungitstashfirst,andthenrungitstashpopwhenyouaredone.Coding'sonlyhalfthebattleinsoftwaredevelopment:ourcodealsohastobethoroughlyreviewedbeforerelease.Reviewersthusareanintegralpartofthedevelopmentprocess.Notethatyoudonothavetohaveanyspecialpullorotherprivilegestoreviewpatches:anyonewithPythononhis/hercomputercanreview.Pullrequests(thepreferredavenueforpatches)forsympyarelocatedhere.Feelfreetoviewanyopenpullrequest.EachcontainsaDiscussionsectionforcomments,Commitssectionforviewingtheauthor'scommitfilesanddocumentation,andDiffsectionforviewingallthechangesincode.Tobrowsetherawcodefilesforacommit,selectacommitintheCommitssectionandclickonthe"Viewfile"linktoviewafile.Basedonyourlevelofexpertise,therearetwowaystoparticipateinthereviewprocess:manuallyrunningtestsandusingsympybot.Whicheveroptionyouchoose,youshouldalsomakesurethatthecommittedcodecomplieswiththeWritingdocumentationguidelines.IntheDiscussionsection,youcanaddacommentattheendofthelist,oryoucanclickonindividuallinesofcodeandaddacommentthere.Notethatlinecommentstendtobecomeinvisibleasamendmentstothepullrequestchangeorremovethelines.Thecommentsarenotlost,justamouseclickaway,butwillnotbereadilyvisibleanymore.Whendiscussingpatches,bepoliteandsticktothepointofthepatch.GitHubhaspublishedanexcellentsetofguidelinesforpullrequestsitisrecommendedreadingforreviewersaswellascoders.Ifyouprefertotestcodemanually,youwillfirsthavetosetupyourenvironmentasdescribedintheWorkflowprocesssection.Then,youneedtoobtainthepatchedfiles.Ifyou'rereviewingapullrequest,youshouldgettherequestedbranchintoyoursympyfolder.Gointoyourfolderandexecute(beingtheusernameofthepullrequesterandbeingthegitbranchofthepullrequest):$gitremoteaddgit://github.com//sympy.git$gitfetch$gitcheckoutb/Afterobtainingthepullrequestorpatch,gotoyoursympyrootdirectoryandexecute:$./bin/test$./bin/doctestIfthereareanyproblems,notifytheauthorinthepullrequestbycommenting.Agoodoptionforbothnewandveterancodereviewersisthesympybotprogram,whichautomaticallytestscodeinpullrequestsandpoststheresultsintheappropriatepullrequests.Torunsympybot,downloadthearchiveanddecompressit.Gointothefolderandexecute:$./sympybotlistThiswilllistallopenpullrequestsonGitHub.Toreviewapullrequestandrunalltests,execute:$./sympybotreviewReviewingpatchesManualtestingSympybotAlternatively,toreviewallopenpullrequests,execute:$./sympybotreviewallThereviewcommandwillposttheresultsofalltestedpullrequestsintheappropriateGithubpage.Formoreinformationonsympybot,visitthereadme.Apullrequestorpatchmustmeetthefollowingrequirementsduringreviewbeforebeingconsideredasreadyforrelease.Alltestsmustpass.Rationale:Weneedtomakesurewe'renotreleasingbuggycode.Ifnewfeaturesarebeingimplementedand/orbugfixesareadded,testsshouldbeaddedforthemaswell.Thereviews(atleast1)mustallbepositive.Rationale:We'dlikeeveryonetoagreeonthemeritsofthepatch.Ifthereareconflictingopinions,thereviewersshouldreachaconsensus.Thepatchmusthavebeenpostedforatleast24hours.Rationale:Thisgivesachanceforeveryonetolookatthepatch.ThispageisbaseduponpresentSymPypages[26],GitHubhelp[89],[1112]andinspiredbySageguide[10]:[1] http://lkml.org/lkml/2000/8/25/132[2] http://docs.sympy.org/dev/sympypatchestutorial.html#quickstart[3] http://sympy.org/development.html[4] https://github.com/sympy/sympy/wiki[5] https://github.com/sympy/sympy/wiki/Pushingpatches[6] https://github.com/sympy/sympy/wiki/Gettingthebleedingedge[7] https://github.com/sympy/sympy/wiki/Githgrosettastone[8] http://help.github.com/pullrequests/[9] http://help.github.com/forkarepo/[10] http://sagemath.org/doc/developer/[11] (1,2)http://help.github.com/linuxsetupgit/[12] http://help.github.com/troubleshootingssh/RequirementsforinclusionReferences