Sage Developer's Guide - Mirrors

More documents

Recommendations

Info

Sage Developer’s Guide, Release 6.1.11.1 Contributing to the Sage Source Code1.1.1 Create a TicketSuppose you have written an algorithm for calculating the last twin prime, and want to add it to Sage. You would firstopen a ticket for that:[user@localhost]$ sage -dev create-ticketThis will give you an editor in which you can give a summary and a description of what you want to do. If you are notsure which values to put for the other fields, you can leave the defaults or have a look at The Ticket Fields. After youclose the editor, a new ticket will be opened on the trac server. From that point on, everyone can see what you intendto do which lets us avoid duplicating work. If you want to cancel the creation of a ticket, then you can just save anempty file. This will abort the operation.Alternatively, you can use the web interface to the Sage trac development server to open a new ticket, just log in andclick on “Create Ticket”.1.1.2 Editing the Source CodeIf you want to work on a ticket which you or somebody else created, you first need to make a local “branch”. Thedevelopment scripts maintain a mapping between local branches and trac tickets. Creating a new local branch for aticket is easy:[user@localhost]$ sage -dev checkout --ticket 1729On ticket #1729 with associated local branch "ticket/1729".# Use "sage --dev merge" to include another ticket/branch.# Use "sage --dev commit" to save changes into a new commit.Essentially, a branch is a copy (except that it doesn’t take up twice the space) of the Sage source code where you canstore your modifications to the Sage source code and which you can upload to trac tickets. Your new branch is nowcalled ticket/. Unless you upload (“push”) it, see below, it will only be on your local system andnot visible to anyone else.At this point you can start editing the source code. The subsequent chapters of this developer guide explain how yourcode should look like to fit into Sage, and how we ensure high code quality throughout. Whenever you have reachedone of your goals, you should make a commit. This takes a snapshot of the whole Sage source code that you have beenworking on and records the changes into your local branch:[user@localhost]$ sage -dev commitCommit your changes to branch "ticket/1729"? [Yes/no] y# Use "sage --dev push" to push your commits to the trac server once you are# done.You will be asked to write a message describing your changes. It is common to write a one line summary, then a blankline, and then a 1-2 paragraph explanation of your changes. If your changes are minor, then just the one-line summarycan be enough.If you are working on a larger project, it can be useful to break up your work into multiple commits: Each commitis saved, enabling you to retrieve older versions of files from the repository. So, even if you accidentally deletesomething, you can get it back later. Also, if you find a mistake in one of your earlier commits, then you just correctit in the Sage source code and then add another commit on top.4 Chapter 1. Sage Development Process
Sage Developer’s Guide, Release 6.1.11.1.3 Uploading Changes to TracAt some point, you may wish to share your changes with the rest of us: maybe it is ready for review, or maybe you arecollaborating with someone and want to share your changes “up until now”. This is simply done by:[user@localhost]$ sage -dev pushOn trac, your remote branch will be called u//ticket/. This name will automaticallybe added to the “Branch:” field on the ticket. Other developers then know where to find your work in the gitrepository.It is common to go through some iterations of sage -dev commit before you upload, and you will probably alsohave uploaded a few times before your changes are ready for review.If you are happy with the changes you uploaded, you want somebody else to review them, so they can be included intothe next version of Sage. If your ticket is ready for review, you should set it to needs_review on the trac server.This can be done though the web interface, or, alternatively, using the development scripts. For the latter, run:[user@localhost]$ sage -dev edit-ticketThis will give you an editor in which you can edit the ticket. Change the status to:Status: needs_reviewAnd add yourself as an author for that ticket by inserting the following as the first line:Authors: Your Real NameIf you want to add an additional comment for potential reviewers, run:[user@localhost]$ sage -dev comment1.1.4 Starting Without a TicketYou might not want to create a trac ticket for your changes. For example, if you are only working on your own codeor if you are making experimental changes that you are likely to throw away if they do not work out. In that case, youcan also start a branch that only lives in your local repository. To do this, you use checkout but specify a branch nameinstead of the ticket number. For example, to create a new branch my_branch, you would run:[user@localhost]$ sage -dev checkout --branch my_branchThis is assuming that you do not already have a local branch called my_branch. If that were the case, you would justswitch to the already-existing branch. Once on your branch, you can work with it as described in Editing the SourceCode.You can upload your local branch later to an existing ticket. This works exactly like in the case where you started witha ticket, except that you have to specify the ticket number. That is:[user@localhost]$ sage -dev push --ticket where you have to replace with the number of the trac ticket.1.2 MergingAs soon as you are working on a bigger project that spans multiple tickets you will want to base your work on branchesthat have not been merged into Sage yet. This is natural in collaborative development, and in fact you are very much1.2. Merging 5
Page 1: Sage Developer’s GuideRelease 6.1
Page 4 and 5: 7 Indices and tables 129Bibliograph
Page 6 and 7: Sage Developer’s Guide, Release 6
Page 58 and 59:
Sage Developer’s Guide, Release 6
Page 60 and 61:
Page 62 and 63:
Page 64 and 65:
Page 66 and 67:
Page 68 and 69:
Page 70 and 71:
Page 72 and 73:
Page 74 and 75:
Page 76 and 77:
Page 78 and 79:
Page 80 and 81:
Page 82 and 83:
Page 84 and 85:
Page 86 and 87:
Page 88 and 89:
Page 90 and 91:
Page 92 and 93:
Page 94 and 95:
Page 96 and 97:
Page 98 and 99:
Page 100 and 101:
Page 102 and 103:
Page 104 and 105:
Page 106 and 107:
Page 108 and 109:
Page 110 and 111:
Page 112 and 113:
Page 114 and 115:
Page 116 and 117:
Page 118 and 119:
Page 120 and 121:
Page 122 and 123:
Page 124 and 125:
Page 126 and 127:
Page 128 and 129:
Page 130 and 131:
Page 132 and 133:
Page 134 and 135:
Page 136 and 137:
show all

Sage Developer's Guide - Mirrors

Create successful ePaper yourself

Delete template?

Save as template?