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.

Developmentworkflow

Introduction

Howtosendapatch

3. 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/pep0257

Inparticular,

Use4spacesforindentationlevels.

Usealllowercasefunctionnameswithwordsseparatedbyunderscores.Forexample,youareencouragedtowritePythonfunctionsusingthenamingconvention

defset_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,primepi

References==========..[1]http://primes.utm.edu/glossary/xpage/BertrandsPostulate.html

Examples========>>>fromsympyimportprime>>>prime(10)29>>>prime(1)2

"""

CodingconventionsinSympy

StandardPythoncodingconventions

Documentationstrings

FormoreinformationseeWritingdocumentationarticleonwiki.

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,division

atthetopofeachfile.Thiswillmakesurethatprintisafunction,andthat1/2doesfloatingpointdivisionandnotintegerdivision.Youshouldalsobeawarethatallimportsareabsolute,soimportmodulewillnotworkifmoduleisamoduleinthesamedirectoryasyourfile.Youwillneedtouseimport.module.

Creatingofenvironmentisonceonly.

SymPyhasaharddependencyonthempmathlibrary(version>=0.19).Youshouldinstallitfirst,pleaserefertothempmathinstallationguide.

ToinstallgitinLinuxlikesystemsyoucandoitviayournativepackagemanagementsystem:

$yuminstallgit

or:

$sudoaptgetinstallgit

InWindowssystems,firstofall,installPythonfrom:

http://python.org/download/

bydownloadingthe"Python2.7Windowsinstaller"(orPython2.6or2.5)andrunningit.ThendonotforgettoaddPythontothe$PATHenvironment.

OnWindowsandMacOSX,theeasiestwaytogetgitistodownloadGitHub'ssoftware,whichwillinstallgit,andalsoprovideaniceGUI(thistutorialwillbebasedonthe

Python3

Workflowprocess

Createyourenvironment

Installmpmath

Installgit

commandlineinterface).Note,youmayneedtogointotheGitHubpreferencesandchoosethe"InstallCommandLineTools"optiontogetgitinstalledintotheterminal.

IfyoudodecidetousetheGitHubGUI,youshouldmakesurethatany"syncdoesrebase"optionisdisabledinthesettings.

SympydevelopmentusesafewtoolsthatarenotincludedinabasicPythondistribution.Youwon'treallyneedthemuntilyouaregettingreadytosubmitapullrequest,buttosavetimelater,youcaninstall:

Sphinxdocumentationgenerator(packagesphinxdoconDebianbasedsystems)Pythoncoveragelibrary(packagepythoncoverage)Programsneededforbuildingdocs,suchasrsvgconvert.Anuptodatelistisismaintainedindoc/README.rst

Gittrackswhomakeseachcommitbycheckingtheusersnameandemail.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=logstat

Itcanbeconvenientinfuturetotunethebashprompttodisplaythecurrentgitbranch.

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:

Installothersoftware

Basicgitsettings

Advancedtuning

$gitclonegit://git.kernel.org/pub/scm/git/git.git$cpgit/contrib/completion/gitcompletion.bash~/.gitcompletion.sh

Readinstructionsin'~/.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/free

ThencreateyourownforkoftheSymPyproject(ifyouhavenotyet).GototheSymPyGitHubrepository:

https://github.com/sympy/sympy

andclicktheForkbutton.

NowyouhaveyourownrepositoryfortheSymPyproject.IfyourusernameinGitHubismynickthentheaddressoftheforkedprojectwilllooksomethinglike:

https://github.com/mynick/sympy

SometoolsconnecttoGitHubwithoutSSH.TousethesetoolsproperlyyouneedtofindandconfigureyourAPIToken.

OnGitHub,clickAccountSettingsthenAccountAdmin.

CreateGitHubaccount

Enterthecodebelow,replacingthemynickand012apitokenwithyourown:

$gitconfigglobalgithub.usermynick$gitconfigglobalgithub.token012apitoken

Note:ifyoueverchangeyourGitHubpassword,anewtokenwillbecreatedandwillneedtobeupdated.

Note:GitHubnolongerusesAPItokens.Youcanskipthisstep.

OnyourmachinebrowsetowhereyouwouldliketostoreSymPy,andclone(download)thelatestcodefromSymPy'soriginalrepository(about20MiB):

$gitclonegit://github.com/sympy/sympy.git$cdsympy

Thenassignyourreadandwriterepotoaremotecalled"github":

$gitremoteaddgithubgit@github.com:mynick/sympy.git

FormoreinformationaboutGitHubforkingandtuningsee:[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.19

YounowhavetwoenvironmentsthatyoucanusefortestingyourdevelopmentcopyofSymPy.Forexample,cloneyourSymPyforkfromGithub:

$gitclonegit@github.com:/sympy.git

CloningSymPy

SetupSSHkeys

VirtualEnvironments

$cdsympy

NowactivatethePython2.7environment:

$sourceactivatesympydevpy27

NotethatonWindowssourceisnotrequiredinthecommand.AndruntheSymPytests:

(sympydevpy27)$bin/test

Afterthetestsrun,thentrythetestsinthePython3.4environment:

(sympydevpy27)$sourcedeactivate$sourceactivatesympydevpy34(sympydevpy34)$bin/test

YoucanalsoinstallSymPyintotheenvironmentifyouwish(soyoucanusethedevelopmentversionfromanylocationonyourfilesystem):

(sympydevpy34)$pythonsetup.pyinstall

Ifyouprefervirtualenv,theprocessissimilar,excepttheswitchbetweenPython2and3isn'tassimple.

Typically,youwillcreateanewbranchtobeginworkonanewissue.Alsopullrequestrelatedwiththem.

Abranchnameshouldbrieflydescribethetopicofthepatchorpullrequest.Ifyouknowtheissuenumber,thenthebranchnamecouldbe,forexample,1234_sequences.Tocreateandcheckout(thatis,makeittheworkingbranch)anewbranch

$gitbranch1234_sequences$gitcheckout1234_sequences

orinonecommandusing

$gitcheckoutb1234_sequences

Toviewallbranches,withyourcurrentbranchhighlighted,type:

$gitbranch

Andremember,nevertypethefollowingcommandsinmaster:gitmerge,gitcommit,gitrebase.

...

Donotforgetthatallnewfunctionalityshouldbetested,andallnewmethods,functions,andclassesshouldhavedoctestsshowinghowtousethem.

Keepinmind,doctestsarenottests.Thinkofthemasexamplesthathappentobetested.Somekeydifferences:

writedocteststobeinformativewriteregularteststocheckforregressionsand

Createaseparatebranch

Codemodification

cornercases.doctestscanbechangedatanytimeregulartestsshouldnotbechanged.

Inparticular,weshouldbeabletochangeordeleteanydoctestatanytimeifitmakesthedocstringbettertounderstand.

Toensureeverythingstaysinshape,letsseeifalltestspass:

$./bin/test$./bin/doctest

EachcommandwillshowaDONOTCOMMITmessageifanyofthetestsitrunsdoesnotpass.

bin/testandbin/doctestdofasttests(thosethattakeseconds).You'llwanttorunthemwheneveryourcodeissupposedtoworkandnotbreakanything.

Youcanalsorunbin/testslow,toruntheslowtests(thosethatmaytakeminuteseach).

Codequality(unwantedspacesandindents)arecheckedby./bin/testutilitiestoo.Butyoucanseparatelyrunthistestwiththehelpofthiscommand:

$./bin/testquality

Ifyouhavetrailingwhitespaceitwillshowerrors.Thisonewillfixunwantedspaces.

$./bin/strip_whitespace

Ifyouwanttotestonlyonesetofteststry:

$./bin/testsympy/concrete/tests/test_products.py

Butrememberthatalltestsshouldpassbeforecommitting.

NotethatalltestswillberunwhenyoumakeyourpullrequestautomaticallybyTravisCI,sodonotworrytoomuchaboutrunningeverypossibletest.Youcanusuallyjustrun:

$./bin/testmod$./bin/doctestmod

wheremodisthenameofthemodulethatyoumodified.

Youcancheckwhatfilesarechanged:

$gitstatus

Addnewfilestotheindexifnecessary:

$gitaddnew_file.py

Checktotalchanges:

$gitdiff

BesurethatalltestsofSymPypass

Committhechanges

Youarereadytocommitchangeslocally.Acommitalsocontainsacommitmessagewhichdescribesit.Seethenextsectionforguidelinesonwritinggoodcommitmessages.Type:

$gitcommit

Aneditorwindowwillappearautomaticallyinthiscase.InLinux,thisisvimbydefault.Youcanchangewhateditorpopsupbychangingthe$EDITORshellvariable.

Alsowiththehelpofoptionayoucantellthecommandcommittoautomaticallystagefilesthathavebeenmodifiedanddeleted,butnewfilesyouhavenottoldgitaboutwillnotbeaffected,e.g.,:

$gitcommita

Ifyouwanttostageonlypartofyourchanges,youcanusetheinteractivecommitfeature.Justtype:

$gitcommitinteractive

andchoosethechangesyouwantintheresultinginterface.

Thereareonlytwoformattingrulesforcommitmessages

Thereshouldbeasinglelinesummaryof71charactersorlesswhichallowstheonelineformofthelogtodisplaythesummarywithoutwrapping.Acommonconventionistonotendthesummarywitha..Additionaldetailscanbegivenafterthesummary.Makesuretoleaveablanklineafterthesummaryandtokeepalllinesto78charactersorlesssotheycanbeeasilybereadinterminalswhichdon'tautomaticallywraplines.

Hereisanexamplecommitmessage(fromthecommit[bf0e81e12a2f75711c30f0788daf4e58f72b2a41],whichispartoftheSymPyhistory):

integrals:Improvedspeedofheurisch()andrevisedtests

Improvedspeedofantiderivativecandidateexpansionandsolutionphasesusingexplicitdomainsandsolve_lin_sys().Theupsideofthischangeisthatlargeintegrals(thosethatgeneratelotsofmonomials)arenowcomputed*much*faster.ThedownsideisthatintegralsinvolvingDerivative()don'tworkanymore.I'mnotsureiftheyreallyusedtoworkproperlyoritwasjustacoincidenceand/orbadimplementation.Thisneedsfurtherinvestigation.

Example:

In[1]:fromsympy.integrals.heurischimportheurisch

In[2]:f=(1+x+x*exp(x))*(x+log(x)+exp(x)1)/(x+log(x)+exp(x))**2/x

In[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)

Writingcommitmessages

Previouslyittook450secondsand4GBofRAMtocompute.

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_sequences

ThiswillsendyourlocalchangestoyourforkoftheSymPyrepository.Thennavigatetoyourrepositorywiththechangesyouwantsomeoneelsetopull:

https://github.com/mynick/sympy

Selectbranch,andpressthePullRequestbutton.

AfterpressingthePullRequestbutton,youarepresentedwithapreviewpagewhereyoucanenteratitleandoptionaldescription,seeexactlywhatcommitswillbeincludedwhenthepullrequestissent,andalsoseewhothepullrequestwillbesentto:

CreateapatchfileorpullrequestforGitHub

Ifyouresendingfromatopicbranch,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.

SeealsoUpdatingyourpullrequest

Ifafteratimeyouneedtomakechangesinpullrequestthenthebestwayistoaddanewcommitinyoulocalrepositoryandsimplyrepeatpushcommand:

$gitcommit$gitpushgithub1234_sequences

Notethatifyoudoanyrebasingorinanywayedityourcommithistory,youwillhavetoaddthef(force)optiontothepushcommandforittowork:

$gitpushfgithub

Youdon'tneedtodothisifyoumerge,whichistherecommendedway.

Updatingyourpullrequest

Sometimes,youmayneedtomergeyourbranchwiththeupstreammaster.Usuallyyoudon'tneedtodothis,butyoumayneedtoif

Someonetellsyouthatyourbranchneedstobemergedbecausetherearemergeconflicts.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:

ABCmaster

Thenwehavedivergentbranch1234_sequences:

ABCmaster\ab1234_sequences

Inthemeantimetheremotesympy/sympymasterrepositorywasupdatedtoo:

ABCDorigin/masterABCmaster\ab1234_sequences

Therearebasicallytwowaystogetuptodatewithachangedmaster:rebasingandmerging.Mergingisrecommended.

Mergingcreatesaspecialcommit,calleda"mergecommit",thatjoinsyourbranchandmastertogether:

ABCDorigin/master\\\Mmerge\/ab1234_sequences

NotethatthecommitsA,B,C,andDfrommasterandthecommitsaandbfrom1234_sequencesremainunchanged.Onlythenewcommit,M,isaddedto1234_sequences,whichmergesinthenewcommitbranchfrommaster.

Rebasingessentiallytakesthecommitsfrom1234_sequencesandreappliesthemonthelatestmaster,sothatitisasifyouhadmadethemfromthelatestversionofthatbranchinstead.Sincethesecommitshaveadifferenthistory,theyaredifferent(theywillhavedifferentSHA1hashes,andwilloftenhavedifferentcontent):

ABCDa'b'origin/master

Synchronizationwithmastersympy/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$gitpull

Thisresultsin:

ABCDmaster\ab1234_sequences

Thenmergeyour1234_sequencesbranchfrom1234_sequences:

$gitcheckout1234_sequences$gitmergemaster

Ifthelastcommandtellsyouthatconflictsmustbesolvedforafewindicatedfiles.

Ifthat'sthecasethenthemarks>>>andand

Sotheresultwillbelikethat(automaticmergingc):

ABCDmaster\\abM1234_sequences

Note:mergingisrecommendedoverrebasing.

Thefinalaim,thatwewanttoobtainis:

ABCDmaster\ab1234_sequences

Thewaytodoitisfirstofalltomergelocalrepositorywiththeremotesympy/sympy:

$gitcheckoutmaster$gitpull

Soweobtain:

ABCDmaster\ab1234_sequences

Then:

$gitcheckout1234_sequences$gitrebasemaster

Notethatthislastonewillrequireyoutofixsomemergeconflictsiftherearechangestothesamefileinmasterand1234_sequences.Openthefilethatittellsyouiswrong,fixthecodewith>>>and

925d88fxsequencesbaseimplementation.

Thenrunrebasecommandininteractivemode:

$gitrebaseinteractive925d88fx

Oryoucanuseotherwaystopointtocommits,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'slogmessage

Toeditacommitmessage,changepicktoreword(oronoldversionsofgit,toedit)forthosethatyouwanttoeditandsavethatfile.

Tosquashtwocommitstogether,changepicktosquash.Toremoveacommit,justdeletethelinewiththecommit.

Toeditacommit,changepicktoedit.

Afterthat,gitwilldropyoubackintoyoureditorforeverycommityouwanttoreword,andintotheshellforeverycommityouwantedtoedit:

$(Changethecommitinanywayyoulike.)$gitcommitamendm"yournewmessage"$gitrebasecontinue

Forcommitsthatyouwanttoedit,itwillstop.Youcanthendo:

$gitresetmixedHEAD^

Thiswill"uncommit"allthechangesfromthecommit.Youcanthenrecommitthemhoweveryouwant.Whenyouaredone,remembertodo:

$gitrebasecontinue

Mostofthissequencewillbeexplainedtoyoubytheoutputofthevariouscommandsofgit.Continueuntilitsays:

Successfullyrebasedandupdatedrefs/heads/master.

Ifatanypointyouwanttoaborttherebase,do:

$gitrebaseabort

Warning: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/doctest

Ifthereareanyproblems,notifytheauthorinthepullrequestbycommenting.

Agoodoptionforbothnewandveterancodereviewersisthesympybotprogram,whichautomaticallytestscodeinpullrequestsandpoststheresultsintheappropriatepullrequests.Torunsympybot,downloadthearchiveanddecompressit.Gointothefolderandexecute:

$./sympybotlist

ThiswilllistallopenpullrequestsonGitHub.Toreviewapullrequestandrunalltests,execute:

$./sympybotreview

Reviewingpatches

Manualtesting

Sympybot

Alternatively,toreviewallopenpullrequests,execute:

$./sympybotreviewall

ThereviewcommandwillposttheresultsofalltestedpullrequestsintheappropriateGithubpage.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/

Requirementsforinclusion

References