Skip to content
This repository has been archived by the owner on Feb 1, 2023. It is now read-only.

migration from trac to Git**b

Jump to bottom
Matthias Köppe edited this page Oct 2, 2022 · 87 revisions

See also: https://trac.sagemath.org/ticket/30363

Proposed workflow on GitHub (with transition guide from Trac)

  • One time action: Instead of depositing an SSH public key on Trac:

  • One time action: Instead of adding a git remote named trac:

    • Create your personal GitHub fork of the main repository https://github.com/sagemath/sage - this will become a repository in https://github.com/USERNAME
    • If you already have a clone of a Sage repository on your computer:
      • Check your current git remote repositories: 
        git remote -v
      • If you already have the main Sage repository (https://github.com/sagemath/sage) as a remote, and its name is not upstream, rename it to upstream using git remote rename OLD-NAME upstream
      • Otherwise, add a new remote: 
        git remote add upstream https://github.com/sagemath/sage.git
        Alternatively, use ssh access with your ssh keypair - see (Optional) above: 
        git remote add upstream [email protected]:sagemath/sage.git
      • If you already have a remote named origin and it is not your personal fork, rename this remote to something else using git remote rename origin MY-OLD-ORIGIN
      • Finally, add your fork as a remote via (the URL can be copied from there) 
        git remote add origin https://github.com/USERNAME/sage.git
        Alternatively, with ssh access (see above): 
        git remote add origin [email protected]:USERNAME/sage.git
    • Otherwise (fresh start):
    • (Of course, you can give arbitrary names to your git remotes, but origin and upstream are the established defaults, which will make it easier to use tools such as the GitHub command-line tools.)

  • For reporting a bug, planning an enhancement, describing a project, instead of opening a Trac ticket:

  • For contributing a change that does not address an existing open Issue, instead of opening a Trac ticket and pushing a git branch to it:

    • Create a new local branch based on upstream/develop
    • Push the branch to the remote named origin, i.e to your fork
    • A git message will provide a URL for opening a Pull Request (PR)
    • Create the PR
    • If it is not ready for review, mark the PR as a "Draft"

  • For contributing a change that addresses an existing open Issue, instead of pushing a git branch to a Trac ticket:

  • For finding PRs that are waiting for review, instead of using Trac ticket reports:

  • Instead of adding a comment to a ticket:

    • Add a comment to the Issue
    • If a PR is linked to the Issue, you can alternatively comment on the PR.
    • Where should a comment go?
      • To say that the reported issue is not a bug but a feature, the comment should go on the Issue
      • To point out typos in the changes, the comment should go on the PR
      • ... (add your examples)
    • Generally everyone has a large enough screen to view both the Issue and the PR on their screen simultaneously

  • For reviewing a change:

  • For organizing, instead of using meta-tickets:

    • either open an Issue
      • it can include a checklist of things to do which can be checked off as they are dealt with by various PRs.
    • or create a new Project

Release Manager's workflow

Proposed permissions and protections

Main repository https://github.com/sagemath/sage:

Conversion of Trac tickets and the Trac wiki to GitHub

Conversion script: https://github.com/sagemath/trac-to-github

  • issues there are various technical discussions on the topic

Preview of the converted issues (iteration 0):

To be done: Several iterations of:

  • Convert all Trac tickets and Trac wiki to a temporary repo.
  • Inspect the result and refine the conversion script.

Switchover day (date to be determined; proposed: Nov 1):

  1. Make Trac read-only:
  2. Convert all tickets to Issues in a new repo sagemath/sage-temp. (This preserves the ticket numbers as Issue numbers.)
  3. Rename sagemath/sagetrac-mirror to sagemath/sagetrac-archive and archive it (= set it to readonly).
  4. (Optional:) Create a single-branch fork of sagemath/sage-temp called sagemath/sagetrac-mirror and push all branches (or all branches of open tickets) from sagemath/sagetrac-archive to it. Open PRs from sagemath/sagetrac-mirror to sagemath/sage-temp for all open tickets with attached branches.
  5. Final check that the new repo sagemath/sage-temp is OK.
  6. Rename sagemath/sage to sagemath/sage-old.
  7. Rename the new repo sagemath/sage-temp to sagemath/sage. (Yes, this will work and will break the redirect sagemath/sage -> sagemath/sage-old.)
  8. Transfer the existing (few) issues from sagemath/sage-old to sagemath/sage.
  9. Announce that sagemath/sage is now open for Issues and PRs.

Retrieving data from GitHub

GitHub REST API

Particularly, anything extracting/archiving discussions should probably look at Issues API, because "Pull requests are just issues with code", although there is a separate Pull request review comments API. Special care may need to be taken to preserve cross-references when archiving.

3 minute video demoing importing github repos to gitlab, which emphasizes answers to a lot of natural frequent questions (involving users, issue comments, labels, etc.): https://www.youtube.com/watch?v=VYOXuOg9tQI

Trac #34624: Backup Issues/PRs for projects hosted in https://github.com/sagemath/

Clone this wiki locally