Home

Build instructions

See http://trac.sagemath.org/wiki/QuickStartSageGit

Using Git+Trac without the development scripts

Pushing and pulling branches to Trac

1. In the preferences for your trac account, there is a SSH Keys tab. Add your public keys.

2. The trac server's ssh port is 2222 (rather than the standard 22), so the easiest way to deal with this is add an extra Host to your SSH config file (note that your username should be git). Then you can push and pull using

    git <push|pull> trac:sage.git [ARGS]
   

   An alternative is to add a remote repository to your local sage repository:

    git remote add trac ssh://git@trac.sagemath.org:2222/sage.git -t master
   

   Then you can push and pull using

    git <push|pull> trac [ARGS]
   

3. You have push permissions to branches of the form u/TRAC_USERNAME/*. So for example, I have permissions to do the following

    git push local_branch:u/ohanar/remote_branch
   

   since my trac username is ohanar. However, the following would give me an error

    git push local_branch
    git push local_branch:master
    ...
   

4. To attach a branch to a ticket, push your changes to the trac server and then fill the Branch field in the corresponding ticket with the remote branch name. For example, if I have a local branch named local_branch and I want to attach this branch to ticket #555, I would do

    git push local_branch:u/ohanar/remote_branch
   

   and then on trac, I would fill the Branch field with u/ohanar/remote_branch.

   The Branch field is color coded: red means there is an issue, green means it will merge cleanly into master. If it is red, the tooltip will tell you what is wrong. If it is green, then it will link to a diff of the changes against u/ohanar/build_system. (This is temporary until #14480 is merged into the master branch.)

Applying mercurial patches

During the transition from mercurial to git, you may want or need to apply some patches produced by mercurial. You can use the standard Unix tool patch for this, or you can use git apply. The main thing to realize, for either approach, is that the sage directory structure has changed, and you will need to account for this. The sage library is now in SAGE_ROOT/src instead of SAGE_ROOT/devel/sage.

If you are in the SAGE_ROOT directory, you can apply a patch with

git apply --directory=src --ignore-space-change --whitespace=fix PATCHFILE

Example usage

• Alice has made some changes for ticket 1234, and made them available on trac by uploading a branch named u/alice/1234. Bob wants to review her changes, so he does

    git fetch trac u/alice/1234
    git checkout FETCH_HEAD
  

  Then Bob can test Alice's changes as much as he likes.

• Bob has tested, and now wants to make a very minor change as a reviewer. He does

    git checkout -b ticket/1234
    ... (make the change) ...
    git commit -am 'helpful commit message'
    git push trac ticket/1234:u/bob/1234
  

  Then Bob goes to the ticket page on Trac and makes some changes to tell Alice about his review, the minor change, and the branch he just uploaded: u/bob/1234. Alice can merge that branch with her own if she wants to use Bob's suggestions.

• Later, Alice and Bob decide to collaborate on ticket 4321, where they'll both be making substantial changes. Alice puts a branch on Trac for this at u/alice/4321. The Bob does

    git remote set-branches trac --add u/alice/4321
    git remote update
    git checkout trac/u/alice/4321 -b ticket/4321
  

  Then Bob does a bunch of work and makes a few commits to his local branch, ticket/4321. Alice does the same to her local branch, and pushes them up to the Trach branch she started. Bob wants to merge them in, so he does

    git remote update
    git merge trac/u/alice/4321
  

Transition Status

Done

• build system modifications (except as below)
• git friendly trac server
• development scripts (found at dev_scripts)
  • git backend (pending no more needed functionality)
  • user interface api
• resolve #14781

Needs work

• development scripts (found at dev_scripts)
  • trac backend
    • method to get display ticket, including all comments
    • method to edit whole ticket (easy to do once the previous one is implemented)
  • public interface (SageDev object)
    • doctests and docstrings
    • finish move of SavingDicts (these should be attached to SageDev as opposed to GitInterface, as they were previously)
    • finish revamp to be more pythonic (asking forgiveness, rather than a bunch of if..else blocks)
  • mecurial compatibility scripts
    • SPKG merge script (should be really easy to write using a truncated version of the script I use to manage the git repository)
    • branch -> mercurial patch (that works with whitespace)
    • make download_patch a bit smarter when it comes to urls
• finish cleanup of the mercurial export script (nearly done)
• documentation
  • walk_through.rst needs a major overhaul
  • producing_spkgs.rst and patching_spkgs.rst need updating
    • old style spkgs are deprecated
    • unified repository now
    • package_version.txt
    • checksums.ini (sage-fix-pkg-checksums)
  • producing_patchs.rst needs major overhaul
  • trac.rst probably needs updating
  • other smaller fixups will probably be needed throughout
• buildbot
• patchbot