Developmentworkflow

Introduction
InSymPyweencouragecollaborativework.
Everyoneiswelcometojoinandtoimplementnewfeature,fixsomebug,givegeneral
advice,etc.Also,wetrytodiscusseverythingandtorevieweachother'sworksothat
manyeyescanseemorethusraisingthequality.
Generaldiscussiontakesplaceonsympy@googlegroups.commailinglistandinthe
issues.SomediscussionalsotakesplaceonIRC(ourchannelis#sympyatfreenode).
Assomeofyoualreadyknow,softwaredevelopmentisnotjustcoding.Manynoncoding
taskshavetobedoneinordertoproducegoodcode.Forexample:settingup
infrastructure,designing,testing,documenting,assistingnewdevelopers(wearedoingit
here),andofcourseprogramming.
Butevenprogrammingisnotallaboutwritingthecode,itisaboutwritingthecodeand
preparingitsothatthecodecanbeincludedintheproject.
Bothproducingthecodeandbringingittotheprojectareimportantpartsofthegame
withoutthecodethereisnothingtobringin,andhavingthecodeoutsideisanowinfor
anyone.
Asalreadysaidabove,wereviewchanges.Thisideawasborrowedfromsuccessful
projectslikeLinux,Python,SAGEandmanymore.Inshort,eachchangeisfirstreviewed
byotherdevelopersandonlywhenitisapprovedisthecodepushedin.
Likeittakesefforttowritegoodandclearcode,reviewingother'sworkneedsefforttoo.
Therearegoodpracticeshowtodothissothatreviewingisfunforboththeauthorand
thereviewer.Wetrytofollowthesegoodpractices,andwe'lltrytoshowyouhowtofollow
themtoo.
Whenreviewingother'spatchesyoulearnalot,sowhynotparticipateasareviewertoo?
Anyoneregardlessoftechnicalskillcanhelpreviewcode,andit'sanexcellentwayfor
newcomerstolearnaboutSympy'sdevelopmentprocessandcommunity.

Howtosendapatch
License:NewBSDLicense(seetheLICENSEfilefordetails)coversallfilesintheSymPy
repositoryunlessstatedotherwise.
Thereareafewwaystocreateandsendapatch.
ThebestwayistosendaGitHubpullrequestagainstthesympy/sympyrepository.We'll
reviewitandpushitin.TheGitHubpullrequestisthepreferredmethod,becauseitmakes
iteasyforustoreviewandpushthecodein.
Morequickly,butnotconvenientforreviewingandmerging,istocreateapatchfileusing
gitalone.Thiswaycanbeusedifthepatchhasahighpriorityorissignificant,onlyoneor
twofilesareinvolved,oryoudon'thaveenoughtimetousethepreferredmethod.
AlthoughwearegratefulforanyimprovementsofSympy,westronglyrecommendyou
submityourpatchesaspullrequests:thiswillgreatlyspeeduptheprocessingofthepatch
andensurethatitdoesn'tgetforgottenduetoinactivity.
Thebasicworkflowforbothvariantsisafollows:
1. Createyourenvironment,ifitwasnotcreatedearlier.
2. Createanewbranch.

3. Modifycodeand/orcreatetestsofit.
4. BesurethatalltestsofSymPypass.
5. Onlythencommitchanges.
6. Createpatchfile,orpullrequestfromGitHub.
AllthosearedescribedinthedetailsbelowWorkflowprocess,butbeforeyoureadthat,it
wouldbeusefultoacquaintyourselfwithCodingconventionsinSympy.
Ifyouhaveanyquestionsyoucanaskthemonthemailinglist.

CodingconventionsinSympy
StandardPythoncodingconventions
FollowthestandardStyleGuideforPythonCodewhenwritingcodeforSymPy,as
explainedatthefollowingURLs:
http://www.python.org/dev/peps/pep0008
http://www.python.org/dev/peps/pep0257
Inparticular,
Use4spacesforindentationlevels.
Usealllowercasefunctionnameswithwordsseparatedbyunderscores.For
example,youareencouragedtowritePythonfunctionsusingthenamingconvention
defset_some_value()

insteadoftheCamelCaseconvention.
UseCamelCaseforclassnamesandmajorfunctionsthatcreateobjects,e.g.
classPolynomialRing(object)

Note,however,thatsomefunctionsdohaveuppercaseletterswhereitmakessense.For
example,formatricestheyareLUdecompositionorT(transposition)methods.

Documentationstrings

prime
'sdocstringisanexampleofawellformatteddocstring:

"""Returnthenthprime.
Primesareindexedasprime(1)=2,prime(2)=3,etc....Thenthprimeis
approximatelyn*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
"""

FormoreinformationseeWritingdocumentationarticleonwiki.

Python3
SymPyusesasinglecodebaseforPython2andPython3(thecurrentsupportedversions
arePython2.6,2.7,3.2,and3.3).ThismeansthatyourcodeneedstoruninbothPython
2andPython3.
Tomakethiseasier,therearemanyfunctionsin
sympy.core.compatibility
thatshould
beusedwhentherearedifferencesbetweenthetwoPythonversions.Toseewhatthings
youcanimportfromthatfile,lookatitssource.
IfyouneedtouseadditionalfunctionsormethodsthatchangenamesfromPython2to
Python3,itisfarbettertoaddto
sympy.core.compatibility
andimportfromtherethan
tobloatindividualsourcefileswithversionspecificlogic.Ingeneral,thePython3names
aretobepreferred,butthisisnotanabsoluterequirement.Forexample,thecurrent
codebaseusesxrangeextensively.
Youshouldalsomakesurethatyouhave:
from__future__importprint_function,division

atthetopofeachfile.Thiswillmakesurethat
print
isafunction,andthat
1/2
does
floatingpointdivisionandnotintegerdivision.Youshouldalsobeawarethatallimports
areabsolute,so
importmodule
willnotworkif
module
isamoduleinthesame
directoryasyourfile.Youwillneedtouse
import.module
.

Workflowprocess
Createyourenvironment
Creatingofenvironmentisonceonly.

Installmpmath
SymPyhasaharddependencyonthempmathlibrary(version>=0.19).Youshould
installitfirst,pleaserefertothempmathinstallationguide.

Installgit
ToinstallgitinLinuxlikesystemsyoucandoitviayournativepackagemanagement
system:
$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

commandlineinterface).Note,youmayneedtogointotheGitHubpreferencesand
choosethe"InstallCommandLineTools"optiontogetgitinstalledintotheterminal.
IfyoudodecidetousetheGitHubGUI,youshouldmakesurethatany"syncdoes
rebase"optionisdisabledinthesettings.

Installothersoftware
SympydevelopmentusesafewtoolsthatarenotincludedinabasicPythondistribution.
Youwon'treallyneedthemuntilyouaregettingreadytosubmitapullrequest,buttosave
timelater,youcaninstall:
Sphinxdocumentationgenerator(packagesphinxdoconDebianbasedsystems)
Pythoncoveragelibrary(packagepythoncoverage)
Programsneededforbuildingdocs,suchasrsvgconvert.Anuptodatelistisis
maintainedindoc/README.rst

Basicgitsettings
Gittrackswhomakeseachcommitbycheckingtheusersnameandemail.Inaddition,
weusethisinfotoassociateyourcommitswithyourGitHubaccount.
Tosetthese,enterthecodebelow,replacingthenameandemailwithyourown(global
isoptional).:
$gitconfigglobaluser.name"FirstnameLastname"
$gitconfigglobaluser.email"your_email@youremail.com"

Thenameshouldbeyouractualname,notyourGitHubusername.
Theseglobaloptions(i.e.applyingtoallrepositories)areplacedin~/.gitconfig.Youcan
editthisfiletoaddsetupcolorsandsomehandyshortcuts:
[user]
name=FirstnameLastname
email=your_email@youremail.com
[color]
diff=auto
status=auto
branch=auto
interactive=true
[alias]
ci=commit
di=diffcolorwords
st=status
co=checkout
log1=logpretty=onelineabbrevcommit
logs=logstat

Advancedtuning
Itcanbeconvenientinfuturetotunethebashprompttodisplaythecurrentgitbranch.
Theeasiestwaytodoit,istoaddthesnippetbelowtoyour.bashrcor.bash_profile:
PS1="[\u@\h\W\$(gitbranch2>/dev/null|grepe'\*'|sed's/^..\(.*\
)/{\1}/')]\$"

Butbetteristousegitcompletionfromthegitsource.Thisalsohastheadvantageof
addingtabcompletiontojustabouteverygitcommand.Italsoincludesmanyotheruseful
features,forexample,promptings.Tousegitcompletion,firstdownloadthegitsource
code(about27MiB),thencopythefiletoyourprofiledirectory:

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

Readinstructionsin'~/.gitcompletion.sh'
NotethatifyouinstallgitfromthepackagemanagerinmanyLinuxdistros,thisfileis
alreadyinstalledforyou.Youcancheckifitisinstalledbyseeingiftabcompletionworks
ongitcommands(try,e.g.,gitcommi<TAB>,orgitlogst<TAB>).Youcanalsocheckif
thePS1commandsworkbydoingsomethinglike:
$PS1='\W$(__git_ps1"%s")\$'

Andyourcommandpromptshouldchangetosomethinglike:
sympymaster$

Note,itisimportanttodefineyourPS1usingsinglequotes('),notdoublequotes("),or
elsebashwillnotupdatethebranchname.

CreateGitHubaccount
AsyouaregoingtouseGitHubyoushouldhaveaGitHubaccount.Ifyouhavenotone
yetthensignupat:
https://github.com/signup/free
ThencreateyourownforkoftheSymPyproject(ifyouhavenotyet).GototheSymPy
GitHubrepository:
https://github.com/sympy/sympy
andclicktheForkbutton.

NowyouhaveyourownrepositoryfortheSymPyproject.IfyourusernameinGitHubis
mynickthentheaddressoftheforkedprojectwilllooksomethinglike:
https://github.com/mynick/sympy

SometoolsconnecttoGitHubwithoutSSH.Tousethesetoolsproperlyyouneedtofind
andconfigureyourAPIToken.
OnGitHub,clickAccountSettingsthenAccountAdmin.

Enterthecodebelow,replacingthemynickand012apitokenwithyourown:
$gitconfigglobalgithub.usermynick
$gitconfigglobalgithub.token012apitoken

Note:ifyoueverchangeyourGitHubpassword,anewtokenwillbecreatedandwillneed
tobeupdated.
Note:GitHubnolongerusesAPItokens.Youcanskipthisstep.

CloningSymPy
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].

SetupSSHkeys
ToestablishasecureconnectionbetweenyourcomputerandGitHubseedetailed
instructionsin[11].
IfyouhaveanyproblemswithSSHaccesstoGitHub,readthetroubleshooting
instructionsat[12],oraskusinmaillist.
Andnow,donotforgettogotothe`Createseparatedbranch`_instructionsbefore
modifyingthecode.

VirtualEnvironments
Youmaywanttotakeadvantageofusingvirtualenvironmentstoisolateyour
developmentversionofSymPyfromanysystemwideinstalledversions,e.g.from
apt
getinstallpythonsympy
.Therearetwoleadingvirtualenvironmenttools,virtualenv

andconda.Condahastheadvantagethatallsoftwareinstallsarebinaryandthatyoucan
easilyswitchbetweenpythonversions.Hereisanexampleofusingcondatocreatetwo
developmentvirtualenvironments,oneforpython2.7andoneforpython3.4:
$condacreatensympydevpy27python=2.7mpmath>=0.19
$condacreatensympydevpy34python=3.4mpmath>=0.19

Younowhavetwoenvironmentsthatyoucanusefortestingyourdevelopmentcopyof
SymPy.Forexample,cloneyourSymPyforkfromGithub:
$gitclonegit@github.com:<yourgithubusername>/sympy.git

$cdsympy

NowactivatethePython2.7environment:
$sourceactivatesympydevpy27

NotethatonWindows
source
isnotrequiredinthecommand.AndruntheSymPytests:
(sympydevpy27)$bin/test

Afterthetestsrun,thentrythetestsinthePython3.4environment:
(sympydevpy27)$sourcedeactivate
$sourceactivatesympydevpy34
(sympydevpy34)$bin/test

YoucanalsoinstallSymPyintotheenvironmentifyouwish(soyoucanusethe
developmentversionfromanylocationonyourfilesystem):
(sympydevpy34)$pythonsetup.pyinstall

Ifyouprefervirtualenv,theprocessissimilar,excepttheswitchbetweenPython2and3
isn'tassimple.

Createaseparatebranch
Typically,youwillcreateanewbranchtobeginworkonanewissue.Alsopullrequest
relatedwiththem.
Abranchnameshouldbrieflydescribethetopicofthepatchorpullrequest.Ifyouknow
theissuenumber,thenthebranchnamecouldbe,forexample,1234_sequences.To
createandcheckout(thatis,makeittheworkingbranch)anewbranch
$gitbranch1234_sequences
$gitcheckout1234_sequences

orinonecommandusing
$gitcheckoutb1234_sequences

Toviewallbranches,withyourcurrentbranchhighlighted,type:
$gitbranch

Andremember,nevertypethefollowingcommandsinmaster:gitmerge,gitcommit,
gitrebase.

Codemodification
...
Donotforgetthatallnewfunctionalityshouldbetested,andallnewmethods,functions,
andclassesshouldhavedoctestsshowinghowtousethem.
Keepinmind,doctestsarenottests.Thinkofthemasexamplesthathappentobetested.
Somekeydifferences:
writedocteststobeinformativewriteregularteststocheckforregressionsand

cornercases.
doctestscanbechangedatanytimeregulartestsshouldnotbechanged.
Inparticular,weshouldbeabletochangeordeleteanydoctestatanytimeifitmakesthe
docstringbettertounderstand.

BesurethatalltestsofSymPypass
Toensureeverythingstaysinshape,letsseeifalltestspass:
$./bin/test
$./bin/doctest

EachcommandwillshowaDONOTCOMMITmessageifanyofthetestsitrunsdoesnot
pass.
bin/testandbin/doctestdofasttests(thosethattakeseconds).You'llwanttorunthem
wheneveryourcodeissupposedtoworkandnotbreakanything.
Youcanalsorun
bin/testslow
,toruntheslowtests(thosethatmaytakeminutes
each).
Codequality(unwantedspacesandindents)arecheckedby./bin/testutilitiestoo.Butyou
canseparatelyrunthistestwiththehelpofthiscommand:
$./bin/testquality

Ifyouhavetrailingwhitespaceitwillshowerrors.Thisonewillfixunwantedspaces.
$./bin/strip_whitespace<file>
Ifyouwanttotestonlyonesetofteststry:
$./bin/testsympy/concrete/tests/test_products.py

Butrememberthatalltestsshouldpassbeforecommitting.
NotethatalltestswillberunwhenyoumakeyourpullrequestautomaticallybyTravisCI,
sodonotworrytoomuchaboutrunningeverypossibletest.Youcanusuallyjustrun:
$./bin/testmod
$./bin/doctestmod

where
mod
isthenameofthemodulethatyoumodified.

Committhechanges
Youcancheckwhatfilesarechanged:
$gitstatus

Addnewfilestotheindexifnecessary:
$gitaddnew_file.py

Checktotalchanges:
$gitdiff

Youarereadytocommitchangeslocally.Acommitalsocontainsacommitmessage
whichdescribesit.Seethenextsectionforguidelinesonwritinggoodcommitmessages.
Type:
$gitcommit

Aneditorwindowwillappearautomaticallyinthiscase.InLinux,thisisvimbydefault.
Youcanchangewhateditorpopsupbychangingthe$EDITORshellvariable.
Alsowiththehelpofoptionayoucantellthecommandcommittoautomaticallystage
filesthathavebeenmodifiedanddeleted,butnewfilesyouhavenottoldgitaboutwillnot
beaffected,e.g.,:
$gitcommita

Ifyouwanttostageonlypartofyourchanges,youcanusetheinteractivecommitfeature.
Justtype:
$gitcommitinteractive

andchoosethechangesyouwantintheresultinginterface.

Writingcommitmessages
Thereareonlytwoformattingrulesforcommitmessages
Thereshouldbeasinglelinesummaryof71charactersorlesswhichallowstheone
lineformofthelogtodisplaythesummarywithoutwrapping.Acommonconvention
istonotendthesummarywitha
.
.
Additionaldetailscanbegivenafterthesummary.Makesuretoleaveablankline
afterthesummaryandtokeepalllinesto78charactersorlesssotheycanbeeasily
bereadinterminalswhichdon'tautomaticallywraplines.
Hereisanexamplecommitmessage(fromthecommit
[bf0e81e12a2f75711c30f0788daf4e58f72b2a41],whichispartoftheSymPyhistory):
integrals:Improvedspeedofheurisch()andrevisedtests
Improvedspeedofantiderivativecandidateexpansionandsolution
phasesusingexplicitdomainsandsolve_lin_sys().Theupsideof
thischangeisthatlargeintegrals(thosethatgeneratelotsof
monomials)arenowcomputed*much*faster.Thedownsideisthat
integralsinvolvingDerivative()don'tworkanymore.I'mnotsure
iftheyreallyusedtoworkproperlyoritwasjustacoincidence
and/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.31s
Walltime:7.32s
Out[3]:
2x2xx2
logx+2x+2xlog(x)++2log(x)+log(x)1
+

2x
x++lo
g(x)

Previouslyittook450secondsand4GBofRAMtocompute.

Somethingstonoteaboutthiscommitmessage:
Thefirstlinegivesabriefdescriptionofwhatthecommitdoes.Toolslike
git
shortlog
orevenGitHubonlyshowthefirstlineofthecommitbydefault,soitis

importanttoconveythemostimportantaspectsofthecommitinthefirstline.
Thefirstlinehas
integrals:
,whichgivescontexttothecommit.Acommitwon't
alwaysbeseeninthecontextofyourbranch,soitisoftenhelpfultogiveeach
commitsomecontext.Thisisnotrequired,though,asitisnothardtolookatthe
commitmetadatatoseewhatfilesweremodifiedoratthecommithistorytoseethe
nearbyrelatedcommits.
Afterthefirstline,thereisaparagraphdescribingthecommitinmoredetail.Thisis
important,asitdescribeswhatthecommitdoes,whichmightbehardtofigureout
justfromlookingatthediff.Italsogivesinformationthatmightnotbeinthediffatall,
suchasknownissues.SuchparagraphsshouldbewritteninplainEnglish.Commit
messagesareintendedforhumanreaders,bothforpeoplewhowillbereviewingyour
coderightnow,andforpeoplewhomightcomeacrossyourcommitinthefuture
whileresearchingsomechangeinthecode.Sometimes,bulletlistsareagoodformat
toconveythechangesofacommit.
Last,thereisanexample.Itisnicetogiveaconcreteexampleincommitsthatadd
newfeatures.Thisparticularexampleisaboutimprovingthespeedofsomething,so
theexampleisabenchmarkresult.
NotethatyoumayfeelfreetouseUnicodecharactersincommitmessages,suchas
outputfromtheSymPyUnicodeprettyprinter.
Trytoavoidshortcommitmessages,like"Fix",andcommitmessagesthatgiveno
context,like"Foundthebug".Whenindoubt,alongercommitmessageisprobablybetter
thanashortone.

CreateapatchfileorpullrequestforGitHub
Besurethatyouareinyourownbranch,andrun:
$gitpushgithub1234_sequences

ThiswillsendyourlocalchangestoyourforkoftheSymPyrepository.Thennavigateto
yourrepositorywiththechangesyouwantsomeoneelsetopull:
https://github.com/mynick/sympy
Selectbranch,andpressthePullRequestbutton.

AfterpressingthePullRequestbutton,youarepresentedwithapreviewpagewhereyou
canenteratitleandoptionaldescription,seeexactlywhatcommitswillbeincludedwhen
thepullrequestissent,andalsoseewhothepullrequestwillbesentto:

Ifyouresendingfromatopicbranch,thetitleisprefilledbasedonthenameofthe
branch.Markdownissupportedinthedescription,soyoucanembedimagesoruse
preformattedtextblocks.

YoucanswitchtotheCommitstabtoensurethatthecorrectsetofchangesisbeingsent.
AndreviewthediffofallchangesbyswitchingtotheFilesChanged.
Enterabrieftitleandinthedescriptionrefertotheissueaddressedoranyrelatedissues
usingreferenceslike"#1234"thosereferencesautomaticallycreatelinksthathelpinthe
reviewofthepullrequest.
Ifthereisn'tanissue,oneshouldbecreatedsoevenifthepullrequestgetsclosed
thereisareferencetoitintheissues.
Ifpossible,refertotheissuenumberinsuchaway,e.g."fixes#1234",thattheissue
getsclosedwhenthepullrequestgetscommitted.
Onceyouveenteredthetitleanddescription,customizedthecommitrange,andreviewed
thecommitsandfilechangestobesent,presstheSendpullrequestbutton.
Thepullrequestissentimmediately.Youretakentothemainpullrequestdiscussionand
reviewpage.Additionally,allrepositorycollaboratorsandfollowerswillseeaneventin
theirdashboard.hThat'sall.
SeealsoUpdatingyourpullrequest

Updatingyourpullrequest
Ifafteratimeyouneedtomakechangesinpullrequestthenthebestwayistoaddanew
commitinyoulocalrepositoryandsimplyrepeatpushcommand:
$gitcommit
$gitpushgithub1234_sequences

Notethatifyoudoanyrebasingorinanywayedityourcommithistory,youwillhaveto
addthef(force)optiontothepushcommandforittowork:
$gitpushfgithub

Youdon'tneedtodothisifyoumerge,whichistherecommendedway.

Synchronizationwithmastersympy/sympy.
Sometimes,youmayneedtomergeyourbranchwiththeupstreammaster.Usuallyyou
don'tneedtodothis,butyoumayneedtoif
Someonetellsyouthatyourbranchneedstobemergedbecausetherearemerge
conflicts.
sympybottellsyouthatyourbranchcouldnotbemerged.
Youneedsomechangefrommasterthatwasmadeafteryoustartedyourbranch.
Note,thataftercloningarepository,ithasadefaultremotecalledoriginthatpointstothe
sympy/sympyrepository.Andyourforkremotenamedasgithub.Youcanobservethe
remotesnameswiththehelpofthiscommand:
$gitremotev
githubgit@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,considerthatwehavethesecommitsinthemasterbranchoflocalgit
repository:
ABCmaster

Thenwehavedivergentbranch1234_sequences:
ABCmaster
\
ab1234_sequences

Inthemeantimetheremotesympy/sympymasterrepositorywasupdatedtoo:
ABCDorigin/master
ABCmaster
\
ab1234_sequences

Therearebasicallytwowaystogetuptodatewithachangedmaster:rebasingand
merging.Mergingisrecommended.
Mergingcreatesaspecialcommit,calleda"mergecommit",thatjoinsyourbranchand
mastertogether:
ABCDorigin/master
\\
\Mmerge
\/
ab1234_sequences

Notethatthecommits
A
,
B
,
C
,and
D
frommasterandthecommits
a
and
b
from

1234_sequences
remainunchanged.Onlythenewcommit,
M
,isaddedto

1234_sequences
,whichmergesinthenewcommitbranchfrommaster.

Rebasingessentiallytakesthecommitsfrom
1234_sequences
andreappliesthemonthe
latestmaster,sothatitisasifyouhadmadethemfromthelatestversionofthatbranch
instead.Sincethesecommitshaveadifferenthistory,theyaredifferent(theywillhave
differentSHA1hashes,andwilloftenhavedifferentcontent):
ABCDa'b'origin/master

Rebasingisrequiredifyouwanttoedityourcommithistory(e.g.,squashcommits,edit
commitmessages,removeunnecessarycommits).Butnotethatsincethisrewrites
history,itispossibletolosedatathisway,anditmakesitharderforpeoplereviewingyour
code,becausetheycannolongerjustlookatthe"newcommits"theyhavetolookat
everythingagain,becauseallthecommitsareeffectivelynew.
Thereareseveraladvantagestomerginginsteadofrebasing.Rebasingreapplieseach
commititerativelyovermaster,andifthestateofthefileschangedbythatcommitis
differentfromwhenitwasoriginallymade,thecommitwillchange.Thismeanswhatyou
canendupgettingcommitsthatarebroken,orcommitsthatdonotdowhattheysaythey
do(becausethechangeshavebeen"rebasedout").Thiscanleadtoconfusionif
someoneinthefuturetriestotestsomethingbycheckingoutcommitsfromthehistory.
Finally,mergeconflictresolutionscanbemoredifficultwithrebasing,becauseyouhaveto
resolvetheconflictsforeachindividualcommit.Withmerging,youonlyhavetoresolve
theconflictsbetweenthebranches,notthecommits.Itisquitecommonforamergetonot
haveanyconflictsbutforarebasetohaveseveral,becausetheconflictsare"already
resolved"bylatercommits.
Mergingkeepseverythingintact.Thecommitsyoumakeareexactlythesame,downto
theSHA1hash,whichmeansthatifyoucheckoutacommitfromamergedbranch,itis
exactlythesameascheckingitoutfromanonmergedbranch.Whatitdoesinsteadis
createasinglecommit,themergecommit,thatmakesitsothatthehistoryisbothmaster
andyourbranch.Thiscommitcontainsallmergeconflictresolutioninformation,whichis
anotheradvantageoverrebasing(allmergeconflictresolutionswhenrebasingare"sifted"
intothecommitsthatcausedthem,makingtheminvisible).
Sincethisguideisaimedatnewgitusers,youshouldbelearninghowtomerge.

Merging
Firstmergeyourlocalrepositorywiththeremote:
$gitcheckoutmaster
$gitpull

Thisresultsin:
ABCDmaster
\
ab1234_sequences

Thenmergeyour1234_sequencesbranchfrom1234_sequences:
$gitcheckout1234_sequences
$gitmergemaster

Ifthelastcommandtellsyouthatconflictsmustbesolvedforafewindicatedfiles.
Ifthat'sthecasethenthemarks>>>and<<<willappearatthosefiles.Fixthecodewith
>>>and<<<aroundittowhatitshouldbe.Youmustmanuallyremoveuselesspieces,
andleaveonlynewchangesfromyourbranch.
Thenbesurethatalltestspass:
$./bin/test
$./bin/doctest

andcommit:
$gitcommit

Sotheresultwillbelikethat(automaticmergingc):
ABCDmaster
\\
abM1234_sequences

Rebasing
Note:mergingisrecommendedoverrebasing.
Thefinalaim,thatwewanttoobtainis:
ABCDmaster
\
ab1234_sequences

Thewaytodoitisfirstofalltomergelocalrepositorywiththeremotesympy/sympy:
$gitcheckoutmaster
$gitpull

Soweobtain:
ABCDmaster
\
ab1234_sequences

Then:
$gitcheckout1234_sequences
$gitrebasemaster

Notethatthislastonewillrequireyoutofixsomemergeconflictsiftherearechangesto
thesamefilein
master
and
1234_sequences
.Openthefilethatittellsyouiswrong,fix
thecodewith>>>and<<<aroundittowhatitshouldbe.
Thenbesurethatalltestspass:
$./bin/test
$./bin/doctest

Thendo:
$gitaddsympy/matrices/your_conflict_file
$gitrebasecontinue

(gitrebasewillalsoguideyouinthis).

Changingofcommitmessages
Theonlytimewhenitisrecommendedtorebaseinsteadofmergeiswhenyouneedto
edityourcommitmessages,orremoveunnecessarycommits.
Note,itismuchbettertogetyourcommitmessagesrightthefirsttime.Seethesectionon
writinggoodcommitmessagesabove.
Considerthesecommitmessages:
$gitlogoneline
7bbbc06bugsfixing
4d6137bsomeadditionalcorrections.

925d88fxsequencesbaseimplementation.

Thenrunrebasecommandininteractivemode:
$gitrebaseinteractive925d88fx

Oryoucanuseotherwaystopointtocommits,e.g.`gitrebaseinteractiveHEAD^^`or
`gitrebaseinteractiveHEAD~2`.
Aneweditorwindowwillappear(notethatorderisreversedwithrespecttothegitlog
command):
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)for
thosethatyouwanttoeditandsavethatfile.
Tosquashtwocommitstogether,changepicktosquash.Toremoveacommit,justdelete
thelinewiththecommit.
Toeditacommit,changepicktoedit.
Afterthat,gitwilldropyoubackintoyoureditorforeverycommityouwanttoreword,and
intotheshellforeverycommityouwantedtoedit:
$(Changethecommitinanywayyoulike.)
$gitcommitamendm"yournewmessage"
$gitrebasecontinue

Forcommitsthatyouwanttoedit,itwillstop.Youcanthendo:
$gitresetmixedHEAD^

Thiswill"uncommit"allthechangesfromthecommit.Youcanthenrecommitthem
howeveryouwant.Whenyouaredone,remembertodo:
$gitrebasecontinue

Mostofthissequencewillbeexplainedtoyoubytheoutputofthevariouscommandsof
git.Continueuntilitsays:
Successfullyrebasedandupdatedrefs/heads/master.

Ifatanypointyouwanttoaborttherebase,do:
$gitrebaseabort

Warning:thiswillrun
gitresethard
,deletinganyuncommittedchangesyouhave.
Ifyouwanttosaveyouruncommittedchanges,run
gitstash
first,andthenrun
git
stashpop
whenyouaredone.

Reviewingpatches
Coding'sonlyhalfthebattleinsoftwaredevelopment:ourcodealsohastobethoroughly
reviewedbeforerelease.Reviewersthusareanintegralpartofthedevelopmentprocess.
Notethatyoudonothavetohaveanyspecialpullorotherprivilegestoreviewpatches:
anyonewithPythononhis/hercomputercanreview.
Pullrequests(thepreferredavenueforpatches)forsympyarelocatedhere.Feelfreeto
viewanyopenpullrequest.EachcontainsaDiscussionsectionforcomments,Commits
sectionforviewingtheauthor'scommitfilesanddocumentation,andDiffsectionfor
viewingallthechangesincode.Tobrowsetherawcodefilesforacommit,selecta
commitintheCommitssectionandclickonthe"Viewfile"linktoviewafile.
Basedonyourlevelofexpertise,therearetwowaystoparticipateinthereviewprocess:
manuallyrunningtestsandusingsympybot.Whicheveroptionyouchoose,youshould
alsomakesurethatthecommittedcodecomplieswiththeWritingdocumentation
guidelines.
IntheDiscussionsection,youcanaddacommentattheendofthelist,oryoucanclick
onindividuallinesofcodeandaddacommentthere.Notethatlinecommentstendto
becomeinvisibleasamendmentstothepullrequestchangeorremovethelines.The
commentsarenotlost,justamouseclickaway,butwillnotbereadilyvisibleanymore.
Whendiscussingpatches,bepoliteandsticktothepointofthepatch.GitHubhas
publishedanexcellentsetofguidelinesforpullrequestsitisrecommendedreadingfor
reviewersaswellascoders.

Manualtesting
Ifyouprefertotestcodemanually,youwillfirsthavetosetupyourenvironmentas
describedintheWorkflowprocesssection.Then,youneedtoobtainthepatchedfiles.If
you'rereviewingapullrequest,youshouldgettherequestedbranchintoyoursympy
folder.Gointoyourfolderandexecute(<username>beingtheusernameofthepull
requesterand<branchname>beingthegitbranchofthepullrequest):
$gitremoteadd<username>git://github.com/<username>/sympy.git
$gitfetch<username>
$gitcheckoutb<branchname><username>/<branchname>

Afterobtainingthepullrequestorpatch,gotoyoursympyrootdirectoryandexecute:
$./bin/test
$./bin/doctest

Ifthereareanyproblems,notifytheauthorinthepullrequestbycommenting.

Sympybot
Agoodoptionforbothnewandveterancodereviewersisthesympybotprogram,which
automaticallytestscodeinpullrequestsandpoststheresultsintheappropriatepull
requests.Torunsympybot,downloadthearchiveanddecompressit.Gointothefolder
andexecute:
$./sympybotlist

ThiswilllistallopenpullrequestsonGitHub.Toreviewapullrequestandrunalltests,
execute:
$./sympybotreview<pullrequest_number>

Alternatively,toreviewallopenpullrequests,execute:
$./sympybotreviewall

Thereviewcommandwillposttheresultsofalltestedpullrequestsintheappropriate
Githubpage.Formoreinformationonsympybot,visitthereadme.

Requirementsforinclusion
Apullrequestorpatchmustmeetthefollowingrequirementsduringreviewbeforebeing
consideredasreadyforrelease.
Alltestsmustpass.
Rationale:Weneedtomakesurewe'renotreleasingbuggycode.
Ifnewfeaturesarebeingimplementedand/orbugfixesareadded,tests
shouldbeaddedforthemaswell.
Thereviews(atleast1)mustallbepositive.
Rationale:We'dlikeeveryonetoagreeonthemeritsofthepatch.
Ifthereareconflictingopinions,thereviewersshouldreachaconsensus.
Thepatchmusthavebeenpostedforatleast24hours.
Rationale:Thisgivesachanceforeveryonetolookatthepatch.

References
ThispageisbaseduponpresentSymPypages[26],GitHubhelp[89],[1112]and
inspiredbySageguide[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/