Development Workflow · GitHub

Download Development Workflow · GitHub

Post on 06-Nov-2015

9 views

Category:

Documents

0 download

Embed Size (px)

DESCRIPTION

Development Workflow GitHub

TRANSCRIPT

<ul><li><p>InSymPyweencouragecollaborativework.</p><p>Everyoneiswelcometojoinandtoimplementnewfeature,fixsomebug,givegeneraladvice,etc.Also,wetrytodiscusseverythingandtorevieweachother'sworksothatmanyeyescanseemorethusraisingthequality.</p><p>Generaldiscussiontakesplaceonsympy@googlegroups.commailinglistandintheissues.SomediscussionalsotakesplaceonIRC(ourchannelis#sympyatfreenode).</p><p>Assomeofyoualreadyknow,softwaredevelopmentisnotjustcoding.Manynoncodingtaskshavetobedoneinordertoproducegoodcode.Forexample:settingupinfrastructure,designing,testing,documenting,assistingnewdevelopers(wearedoingithere),andofcourseprogramming.</p><p>Butevenprogrammingisnotallaboutwritingthecode,itisaboutwritingthecodeandpreparingitsothatthecodecanbeincludedintheproject.</p><p>Bothproducingthecodeandbringingittotheprojectareimportantpartsofthegamewithoutthecodethereisnothingtobringin,andhavingthecodeoutsideisanowinforanyone.</p><p>Asalreadysaidabove,wereviewchanges.ThisideawasborrowedfromsuccessfulprojectslikeLinux,Python,SAGEandmanymore.Inshort,eachchangeisfirstreviewedbyotherdevelopersandonlywhenitisapprovedisthecodepushedin.</p><p>Likeittakesefforttowritegoodandclearcode,reviewingother'sworkneedsefforttoo.Therearegoodpracticeshowtodothissothatreviewingisfunforboththeauthorandthereviewer.Wetrytofollowthesegoodpractices,andwe'lltrytoshowyouhowtofollowthemtoo.</p><p>Whenreviewingother'spatchesyoulearnalot,sowhynotparticipateasareviewertoo?Anyoneregardlessoftechnicalskillcanhelpreviewcode,andit'sanexcellentwayfornewcomerstolearnaboutSympy'sdevelopmentprocessandcommunity.</p><p>License:NewBSDLicense(seetheLICENSEfilefordetails)coversallfilesintheSymPyrepositoryunlessstatedotherwise.</p><p>Thereareafewwaystocreateandsendapatch.</p><p>ThebestwayistosendaGitHubpullrequestagainstthesympy/sympyrepository.We'llreviewitandpushitin.TheGitHubpullrequestisthepreferredmethod,becauseitmakesiteasyforustoreviewandpushthecodein.</p><p>Morequickly,butnotconvenientforreviewingandmerging,istocreateapatchfileusinggitalone.Thiswaycanbeusedifthepatchhasahighpriorityorissignificant,onlyoneortwofilesareinvolved,oryoudon'thaveenoughtimetousethepreferredmethod.</p><p>AlthoughwearegratefulforanyimprovementsofSympy,westronglyrecommendyousubmityourpatchesaspullrequests:thiswillgreatlyspeeduptheprocessingofthepatchandensurethatitdoesn'tgetforgottenduetoinactivity.</p><p>Thebasicworkflowforbothvariantsisafollows:</p><p>1. Createyourenvironment,ifitwasnotcreatedearlier.2. Createanewbranch.</p><p>Developmentworkflow</p><p>Introduction</p><p>Howtosendapatch</p></li><li><p>3. Modifycodeand/orcreatetestsofit.4. BesurethatalltestsofSymPypass.5. Onlythencommitchanges.6. Createpatchfile,orpullrequestfromGitHub.</p><p>AllthosearedescribedinthedetailsbelowWorkflowprocess,butbeforeyoureadthat,itwouldbeusefultoacquaintyourselfwithCodingconventionsinSympy.</p><p>Ifyouhaveanyquestionsyoucanaskthemonthemailinglist.</p><p>FollowthestandardStyleGuideforPythonCodewhenwritingcodeforSymPy,asexplainedatthefollowingURLs:</p><p>http://www.python.org/dev/peps/pep0008http://www.python.org/dev/peps/pep0257</p><p>Inparticular,</p><p>Use4spacesforindentationlevels.</p><p>Usealllowercasefunctionnameswithwordsseparatedbyunderscores.Forexample,youareencouragedtowritePythonfunctionsusingthenamingconvention</p><p>defset_some_value()</p><p>insteadoftheCamelCaseconvention.</p><p>UseCamelCaseforclassnamesandmajorfunctionsthatcreateobjects,e.g.</p><p>classPolynomialRing(object)</p><p>Note,however,thatsomefunctionsdohaveuppercaseletterswhereitmakessense.Forexample,formatricestheyareLUdecompositionorT(transposition)methods.</p><p>prime'sdocstringisanexampleofawellformatteddocstring:</p><p>"""Returnthenthprime.</p><p>Primesareindexedasprime(1)=2,prime(2)=3,etc....Thenthprimeisapproximatelyn*log(n)andcanneverbelargerthan2**n.</p><p>SeeAlso========sympy.ntheory.primetest.isprime,primerange,primepi</p><p>References==========..[1]http://primes.utm.edu/glossary/xpage/BertrandsPostulate.html</p><p>Examples========&gt;&gt;&gt;fromsympyimportprime&gt;&gt;&gt;prime(10)29&gt;&gt;&gt;prime(1)2</p><p>"""</p><p>CodingconventionsinSympy</p><p>StandardPythoncodingconventions</p><p>Documentationstrings</p></li><li><p>FormoreinformationseeWritingdocumentationarticleonwiki.</p><p>SymPyusesasinglecodebaseforPython2andPython3(thecurrentsupportedversionsarePython2.6,2.7,3.2,and3.3).ThismeansthatyourcodeneedstoruninbothPython2andPython3.</p><p>Tomakethiseasier,therearemanyfunctionsinsympy.core.compatibilitythatshouldbeusedwhentherearedifferencesbetweenthetwoPythonversions.Toseewhatthingsyoucanimportfromthatfile,lookatitssource.</p><p>IfyouneedtouseadditionalfunctionsormethodsthatchangenamesfromPython2toPython3,itisfarbettertoaddtosympy.core.compatibilityandimportfromtherethantobloatindividualsourcefileswithversionspecificlogic.Ingeneral,thePython3namesaretobepreferred,butthisisnotanabsoluterequirement.Forexample,thecurrentcodebaseusesxrangeextensively.</p><p>Youshouldalsomakesurethatyouhave:</p><p>from__future__importprint_function,division</p><p>atthetopofeachfile.Thiswillmakesurethatprintisafunction,andthat1/2doesfloatingpointdivisionandnotintegerdivision.Youshouldalsobeawarethatallimportsareabsolute,soimportmodulewillnotworkifmoduleisamoduleinthesamedirectoryasyourfile.Youwillneedtouseimport.module.</p><p>Creatingofenvironmentisonceonly.</p><p>SymPyhasaharddependencyonthempmathlibrary(version&gt;=0.19).Youshouldinstallitfirst,pleaserefertothempmathinstallationguide.</p><p>ToinstallgitinLinuxlikesystemsyoucandoitviayournativepackagemanagementsystem:</p><p>$yuminstallgit</p><p>or:</p><p>$sudoaptgetinstallgit</p><p>InWindowssystems,firstofall,installPythonfrom:</p><p>http://python.org/download/</p><p>bydownloadingthe"Python2.7Windowsinstaller"(orPython2.6or2.5)andrunningit.ThendonotforgettoaddPythontothe$PATHenvironment.</p><p>OnWindowsandMacOSX,theeasiestwaytogetgitistodownloadGitHub'ssoftware,whichwillinstallgit,andalsoprovideaniceGUI(thistutorialwillbebasedonthe</p><p>Python3</p><p>Workflowprocess</p><p>Createyourenvironment</p><p>Installmpmath</p><p>Installgit</p></li><li><p>commandlineinterface).Note,youmayneedtogointotheGitHubpreferencesandchoosethe"InstallCommandLineTools"optiontogetgitinstalledintotheterminal.</p><p>IfyoudodecidetousetheGitHubGUI,youshouldmakesurethatany"syncdoesrebase"optionisdisabledinthesettings.</p><p>SympydevelopmentusesafewtoolsthatarenotincludedinabasicPythondistribution.Youwon'treallyneedthemuntilyouaregettingreadytosubmitapullrequest,buttosavetimelater,youcaninstall:</p><p>Sphinxdocumentationgenerator(packagesphinxdoconDebianbasedsystems)Pythoncoveragelibrary(packagepythoncoverage)Programsneededforbuildingdocs,suchasrsvgconvert.Anuptodatelistisismaintainedindoc/README.rst</p><p>Gittrackswhomakeseachcommitbycheckingtheusersnameandemail.Inaddition,weusethisinfotoassociateyourcommitswithyourGitHubaccount.</p><p>Tosetthese,enterthecodebelow,replacingthenameandemailwithyourown(globalisoptional).:</p><p>$gitconfigglobaluser.name"FirstnameLastname"$gitconfigglobaluser.email"your_email@youremail.com"</p><p>Thenameshouldbeyouractualname,notyourGitHubusername.</p><p>Theseglobaloptions(i.e.applyingtoallrepositories)areplacedin~/.gitconfig.Youcaneditthisfiletoaddsetupcolorsandsomehandyshortcuts:</p><p>[user]name=FirstnameLastnameemail=your_email@youremail.com</p><p>[color]diff=autostatus=autobranch=autointeractive=true</p><p>[alias]ci=commitdi=diffcolorwordsst=statusco=checkoutlog1=logpretty=onelineabbrevcommitlogs=logstat</p><p>Itcanbeconvenientinfuturetotunethebashprompttodisplaythecurrentgitbranch.</p><p>Theeasiestwaytodoit,istoaddthesnippetbelowtoyour.bashrcor.bash_profile:</p><p>PS1="[\u@\h\W\$(gitbranch2&gt;/dev/null|grepe'\*'|sed's/^..\(.*\)/{\1}/')]\$"</p><p>Butbetteristousegitcompletionfromthegitsource.Thisalsohastheadvantageofaddingtabcompletiontojustabouteverygitcommand.Italsoincludesmanyotherusefulfeatures,forexample,promptings.Tousegitcompletion,firstdownloadthegitsourcecode(about27MiB),thencopythefiletoyourprofiledirectory:</p><p>Installothersoftware</p><p>Basicgitsettings</p><p>Advancedtuning</p></li><li><p>$gitclonegit://git.kernel.org/pub/scm/git/git.git$cpgit/contrib/completion/gitcompletion.bash~/.gitcompletion.sh</p><p>Readinstructionsin'~/.gitcompletion.sh'</p><p>NotethatifyouinstallgitfromthepackagemanagerinmanyLinuxdistros,thisfileisalreadyinstalledforyou.Youcancheckifitisinstalledbyseeingiftabcompletionworksongitcommands(try,e.g.,gitcommi,orgitlogst).YoucanalsocheckifthePS1commandsworkbydoingsomethinglike:</p><p>$PS1='\W$(__git_ps1"%s")\$'</p><p>Andyourcommandpromptshouldchangetosomethinglike:</p><p>sympymaster$</p><p>Note,itisimportanttodefineyourPS1usingsinglequotes('),notdoublequotes("),orelsebashwillnotupdatethebranchname.</p><p>AsyouaregoingtouseGitHubyoushouldhaveaGitHubaccount.Ifyouhavenotoneyetthensignupat:</p><p>https://github.com/signup/free</p><p>ThencreateyourownforkoftheSymPyproject(ifyouhavenotyet).GototheSymPyGitHubrepository:</p><p>https://github.com/sympy/sympy</p><p>andclicktheForkbutton.</p><p>NowyouhaveyourownrepositoryfortheSymPyproject.IfyourusernameinGitHubismynickthentheaddressoftheforkedprojectwilllooksomethinglike:</p><p>https://github.com/mynick/sympy</p><p>SometoolsconnecttoGitHubwithoutSSH.TousethesetoolsproperlyyouneedtofindandconfigureyourAPIToken.</p><p>OnGitHub,clickAccountSettingsthenAccountAdmin.</p><p>CreateGitHubaccount</p></li><li><p>Enterthecodebelow,replacingthemynickand012apitokenwithyourown:</p><p>$gitconfigglobalgithub.usermynick$gitconfigglobalgithub.token012apitoken</p><p>Note:ifyoueverchangeyourGitHubpassword,anewtokenwillbecreatedandwillneedtobeupdated.</p><p>Note:GitHubnolongerusesAPItokens.Youcanskipthisstep.</p><p>OnyourmachinebrowsetowhereyouwouldliketostoreSymPy,andclone(download)thelatestcodefromSymPy'soriginalrepository(about20MiB):</p><p>$gitclonegit://github.com/sympy/sympy.git$cdsympy</p><p>Thenassignyourreadandwriterepotoaremotecalled"github":</p><p>$gitremoteaddgithubgit@github.com:mynick/sympy.git</p><p>FormoreinformationaboutGitHubforkingandtuningsee:[8],[9]and[11].</p><p>ToestablishasecureconnectionbetweenyourcomputerandGitHubseedetailedinstructionsin[11].</p><p>IfyouhaveanyproblemswithSSHaccesstoGitHub,readthetroubleshootinginstructionsat[12],oraskusinmaillist.</p><p>Andnow,donotforgettogotothe`Createseparatedbranch`_instructionsbeforemodifyingthecode.</p><p>YoumaywanttotakeadvantageofusingvirtualenvironmentstoisolateyourdevelopmentversionofSymPyfromanysystemwideinstalledversions,e.g.fromaptgetinstallpythonsympy.Therearetwoleadingvirtualenvironmenttools,virtualenvandconda.Condahastheadvantagethatallsoftwareinstallsarebinaryandthatyoucaneasilyswitchbetweenpythonversions.Hereisanexampleofusingcondatocreatetwodevelopmentvirtualenvironments,oneforpython2.7andoneforpython3.4:</p><p>$condacreatensympydevpy27python=2.7mpmath&gt;=0.19$condacreatensympydevpy34python=3.4mpmath&gt;=0.19</p><p>YounowhavetwoenvironmentsthatyoucanusefortestingyourdevelopmentcopyofSymPy.Forexample,cloneyourSymPyforkfromGithub:</p><p>$gitclonegit@github.com:/sympy.git</p><p>CloningSymPy</p><p>SetupSSHkeys</p><p>VirtualEnvironments</p></li><li><p>$cdsympy</p><p>NowactivatethePython2.7environment:</p><p>$sourceactivatesympydevpy27</p><p>NotethatonWindowssourceisnotrequiredinthecommand.AndruntheSymPytests:</p><p>(sympydevpy27)$bin/test</p><p>Afterthetestsrun,thentrythetestsinthePython3.4environment:</p><p>(sympydevpy27)$sourcedeactivate$sourceactivatesympydevpy34(sympydevpy34)$bin/test</p><p>YoucanalsoinstallSymPyintotheenvironmentifyouwish(soyoucanusethedevelopmentversionfromanylocationonyourfilesystem):</p><p>(sympydevpy34)$pythonsetup.pyinstall</p><p>Ifyouprefervirtualenv,theprocessissimilar,excepttheswitchbetweenPython2and3isn'tassimple.</p><p>Typically,youwillcreateanewbranchtobeginworkonanewissue.Alsopullrequestrelatedwiththem.</p><p>Abranchnameshouldbrieflydescribethetopicofthepatchorpullrequest.Ifyouknowtheissuenumber,thenthebranchnamecouldbe,forexample,1234_sequences.Tocreateandcheckout(thatis,makeittheworkingbranch)anewbranch</p><p>$gitbranch1234_sequences$gitcheckout1234_sequences</p><p>orinonecommandusing</p><p>$gitcheckoutb1234_sequences</p><p>Toviewallbranches,withyourcurrentbranchhighlighted,type:</p><p>$gitbranch</p><p>Andremember,nevertypethefollowingcommandsinmaster:gitmerge,gitcommit,gitrebase.</p><p>...</p><p>Donotforgetthatallnewfunctionalityshouldbetested,andallnewmethods,functions,andclassesshouldhavedoctestsshowinghowtousethem.</p><p>Keepinmind,doctestsarenottests.Thinkofthemasexamplesthathappentobetested.Somekeydifferences:</p><p>writedocteststobeinformativewriteregularteststocheckforregressionsand</p><p>Createaseparatebranch</p><p>Codemodification</p></li><li><p>cornercases.doctestscanbechangedatanytimeregulartestsshouldnotbechanged.</p><p>Inparticular,weshouldbeabletochangeordeleteanydoctestatanytimeifitmakesthedocstringbettertounderstand.</p><p>Toensureeverythingstaysinshape,letsseeifalltestspass:</p><p>$./bin/test$./bin/doctest</p><p>EachcommandwillshowaDONOTCOMMITmessageifanyofthetestsitrunsdoesnotpass.</p><p>bin/testandbin/doctestdofasttests(thosethattakeseconds).You'llwanttorunthemwheneveryourcodeissupposedtoworkandnotbreakanything.</p><p>Youcanalsorunbin/testslow,toruntheslowtests(thosethatmaytakeminuteseach).</p><p>Codequality(unwantedspacesandindents)arecheckedby./bin/testutilitiestoo.Butyoucanseparatelyrunthistestwiththehelpofthiscommand:</p><p>$./bin/testquality</p><p>Ifyouhavetrailingwhitespaceitwillshowerrors.Thisonewillfixunwantedspaces.</p><p>$./bin/strip_whitespace</p><p>Ifyouwanttotestonlyonesetofteststry:</p><p>$./bin/testsympy/concrete/tests/test_products.py</p><p>Butrememberthatalltestsshouldpassbeforecommitting.</p><p>NotethatalltestswillberunwhenyoumakeyourpullrequestautomaticallybyTravisCI,sodonotworrytoomuchaboutrunningeverypossibletest.Youcanusuallyjustrun:</p><p>$./bin/testmod$./bin/doctestmod</p><p>wheremodisthenameofthemodulethatyoumodified.</p><p>Youcancheckwhatfilesarechanged:</p><p>$gitstatus</p><p>Addnewfilestotheindexifnecessary:</p><p>$gitaddnew_file.py</p><p>Checktotalchanges:</p><p>$gitdiff</p><p>BesurethatalltestsofSymPypass</p><p>Committhechanges</p></li><li><p>Youarereadytocommitchangeslocally.Acommitalsocontainsacommitmessagewhichdescribesit.Seethenextsectionforguidelinesonwritinggoodcommitmessages.Type:</p><p>$gitcommit</p><p>Aneditorwindowwillappearautomaticallyinthiscase.InLinux,thisisvimbydefault.Youcanchangewhateditorpopsupbychangingthe$EDITORshellvariable.</p><p>Alsowiththehelpofoptionayoucantellthecommandcommittoautomaticallystagefilesthathavebeenmodifiedanddeleted,butnewfilesyouhavenottoldgitaboutwillnotbeaffected,e.g.,:</p><p>$gitcommita</p><p>Ifyouwanttostageonlypartofyourchanges,youcanusetheinteractivecommitfeature.Justtype:</p><p>$gitcommitinteractive</p><p>andchoosethechangesyouwantintheresultinginterface.</p><p>Thereareonlytwoformattingrulesforcommitmessages</p><p>Thereshouldbeasinglelinesummaryof71charactersorlesswhichallowstheonelineformofthelogtodisplaythesummarywithoutwrapping.Acommonconventionistonotendthesummarywitha..Additionaldetailscanbegivenafterthesummary.Makesuretoleaveablanklineafterthesummaryandtokeepalllinesto78charactersorlesssotheycanbeeasilybereadinterminalswhichdon'tautomaticallywraplines.</p><p>Hereisanexamplecommitmessage(fromthecommit[bf0e81e12a2f75711c30f0788daf4e58f72b2a41],whichispartoftheSymPyhistory):</p><p>integrals:Improvedspeedofheurisch()andrevisedtests</p><p>Improvedspeedofantiderivativecandidateexpansionandsolutionphasesusingexplicitdomainsandsolve_lin_sys().Theupsideofthischangeisthatlargeintegrals(thosethatgeneratelotsofmonomials)arenowcomputed*much*faster.ThedownsideisthatintegralsinvolvingDerivative()don'tworkanymore.I'mnotsureiftheyreallyusedtoworkproperlyoritwasjustacoincidenceand/orbadimplementation.Thisneedsfurtherinvestigation.</p><p>Example:</p><p>In[1]:fromsympy.integrals.heurischimportheurisch</p><p>In[2]:f=(1+x+x*exp(x))*(x+log(x)+exp(x)1)/(x+log(x)+exp(x))**2/x</p><p>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)</p><p>Writingcommitmessages</p></li><li><p>Previouslyittook450secondsand4GBofRAMtocompute.</p><p>Somethingstonoteaboutthiscommitmessage:</p><p>Thefirstl...</p></li></ul>