Skip to content

MigrationToGitHub

Jump to bottom
Phil Burk edited this page Mar 16, 2021 · 21 revisions

portaudio_logo.png

Plan for Migrating Repository, Tickets, Wiki to GitHub

Resources and Links

Original High Level Plan by Ross Bencina from September 2019 email

  1. Merge or discard open merge requests
  2. Archive all repos and content currently on Assembla
  3. Work out which new host to use [decided: GitHub]
  4. Port the git repo
  5. Port the wiki
  6. Port/rehost open tickets to new platform, and/or host closed tickets somewhere in static form. For example, this could take the form of a re-skinned static screen-scrape hosted at portaudio.com.
  7. Put Assembla site into some kind of reduced/stub state.

How to Port Repository

GitHub provides a GitHub Importer that can also match and modify authors.

  1. Visit https://github.com/portaudio
  2. Click "Create a new repository"
  3. Click"Import a repository"
  4. Enter "https://github.com/PortAudio/portaudio.git" as the old clone URL
  5. Enter a name="test-migration-1" and click "Begin Import"
  6. Waited two minutes and got: https://github.com/philburk/test-migration-1

The new repo has 12 release tags. The 35 branches were preserved so it would be easy to finish the pending merge requests. Compare these

Ownership for RossBencina, philburk, dmitrykos, dechamps, nickappleton were associated with GitHub accounts by matching emails. One commit from DaShun to add ASIO lib on April 16, 2018 was not matched. Commits before April 10, 2016 have names but they are not matched. That is when we switched from SVN to Git. They probably cannot be matched but at least the original names are on the commits. There are no unmatched commits after April 10, 2016.

.h3 How to Map Old Names from SVN

This hack allows GitHub to match old names before 2016. The email addresses from SVN are stored with a hash for the domain. Everyone has the same hash. For example:

  • rbencina@0f58301d-fd10-0410-b4af-bbb618454e57
  • philburk@0f58301d-fd10-0410-b4af-bbb618454e57

By adding that email address to your GitHub profile, GitHub will match those commits to your account. The email address cannot be verified because it is not real. I don't know if that will cause problems.

OR, here are manual steps provided by Svein Seldal

git clone --mirror [email protected]:portaudio.git
cd portaudio.git
git remote add github [email protected]:${user}/${repo}.git
git push github --all
git push github --tags

Demo of this procedure at https://github.com/sveinse/sandbox4

How to Port Wiki and Tickets

Use the version of assembla2github extended for PortAudio by Svein Seldal. Full instructions are here: https://github.com/sveinse/assembla2github-portaudio#procedure|

Goals, Priorities and Requirements

Goals:

  • Lose as little data as possible.
  • Automate as much as possible
  • Do one or more draft migrations to test/verify
  • No manual edits until after the final automated migration

Git Import

Strong Desire:

  • transfer/translate user names on commits. use GitHub Importer to assign email/user names. Will need each committer’s GitHub user name [GitHub importer will map users with same email address automatically, otherwise: if commits have email addresses, github will match them later if user adds that email address to their account. If we have GitHub user names, can do matching during import. Phil is going to try to make a list of user names that we need based on a test import.]

Project Commiters/Collaborators

  • Committers/Collaborators [deal with manually after automated migration]

Merge Requests

Phil and Ross have reviewed the open merge requests and merged the few that made sense to merge now. The rest of the merge requests will be left open and ported across manually once the GitHub migration is complete.

Wiki

Minimum requirements:

  • all wiki pages [current revision] migrated
  • all images on wiki pages migrated

Extra:

  • older page revisions

Tickets

Minimum requirements:

  • Ticket numbers: Retain ticket numbers -- needed because existing tickets and commit messages reference ticket numbers with # notation. See "Note" below about #223.
  • Don’t need assembla ticket numbers in ticket name e.g. "[#123]" at start of name if we can get github ticket numbers to line up.
  • Assignee
  • Attachments
  • Milestones [DONE?]
  • Status {New, Open, Closed, etc.} [DONE?]
  • Include commenter name in ticket comments somehow [e.g. next to date]
  • Retain ticket fields {Priority, Component, Keywords, Tags}, ideally as labels: https://docs.github.com/en/github/managing-your-work-on-github/applying-labels-to-issues-and-pull-requests

Note: [August 8: seems to be an issue with git ticket numbers being out of sync with our ticket numbers e.g. https://github.com/illuusio/test_portaudio_export/issues/288 is Assembla ticket #289 -- got out of sync on/after number 223. It may be because Ticket #223 is broken in Assembla, or it may be a list instead of a real ticket. So it gets skipped. Assembla Ticket #224 is then assigned index #223 GitHub. We can probably fix this be putting in a dummy Ticket in the Ticket dump file. Compare these two links.

Important:

  • Create tickets either with original user name or special "PortAudio GitHub Import" user that we create
  • Event Dates [especially creation date/close date]

Nice to have:

  • Remove first "[#123] -" from ticket name
  • Fix milestone names e.g. "[#951063] - V19-M3" --> "V19-M3"

PortAudio

Clone this wiki locally