libp2p-issue-migration.md

libp2p issue migration script

See this PR and conversation for context: libp2p/libp2p#86.

Goal

To create a script to migrate issues from go-libp2p inner repos to the top-level repo, applying labels along the way.

Input

A list of repos by GitHub URL (e.g. https://github.com/libp2p/go-libp2p-…) and, for each, a set of labels to apply once the issue has been moved. OK for this to be a map in code (we’re only going to use this tool once).

Process

1. Traverse the list of repos. For each repo:
2. Fetch all issues.
3. For each issue:
   1. Call the GraphQL API transferIssue mutation (https://developer.github.com/v4/mutation/transferIssue/) to transfer the issue to go-libp2p.
   2. Apply the associated labels on the resulting issue. Apply the label immediately after transferring each issue; this gives us good resumption abilities in case something fails midway. (addLabelsToLabelable mutation: https://developer.github.com/v4/mutation/addlabelstolabelable/)
4. Create an issue in the source repo, with a configurable title and body. Ok for these values to be hardcoded in code. This will be an announcement issue that redirects folks to the go-libp2p issue tracker. (createIssue mutation: https://developer.github.com/v4/mutation/createissue/)
5. Pin the issue on the source repo (pinIssue mutation: https://developer.github.com/v4/mutation/pinissue/).

I think you’ll need to perform some init logic to translate the labels from text to their IDs, so they can be used in the addLabelsToLabelable mutation.

I cooked up this example query that retrieves labels from go-libp2p — you’ll probably need to deal with proper pagination though:

{
  repository(owner: "libp2p", name: "go-libp2p") {
    labels(first: 100) {
      nodes {
        name
        id
      }
    }
  }
}

Implementation considerations

• Beware and mindful of GitHub API rate limiting. This script should honour API quotas; make sure we're not tripping over.
• Write this in Go.
• Let's put it under a .scripts directory in the libp2p/libp2p.
• Try using github.com/machinebox/graphql as a GraphQL client.
• If something fails midway, our script should be able to resume properly and in a stateless manner (do not keep track of state, we'll just go over each repo again noticing we have no issues, and not creating the pinned issue). Worst case scenario where things could be left incoherent is if we fail after transferring the issue and before labelling it. In that case, we'll end up with ONE unlabelled issue, and it's not the end of the world.