mirror

Documentation

Overview

Package mirror handles pulling data from Github and feeding it into the git-appraise metadata formats. It's used by both the batch processing tool and the webapp.

Index

• Variables
• func CommentsOverlap(a, b comment.Comment) bool
• func ConvertDiffComment(diffComment *github.PullRequestComment) (*comment.Comment, error)
• func ConvertIssueComment(issueComment *github.IssueComment) (*comment.Comment, error)
• func ConvertPullRequest(pr *github.PullRequest) (*request.Request, error)
• func ConvertPullRequestToReview(pr *github.PullRequest, issueComments []*github.IssueComment, ...) (*review.Review, error)
• func ConvertStatus(repoStatus *github.RepoStatus) (*ci.Report, error)
• func ConvertTime(t time.Time) string
• func GetAllPullRequests(local repository.Repo, remoteUser, remoteRepo string, client *github.Client, ...) ([]review.Review, error)
• func GetAllStatuses(remoteUser, remoteRepo string, client *github.Client, errOutput chan<- error) (map[string][]ci.Report, error)
• func RequestsOverlap(a, b request.Request) bool
• func WriteNewComments(r review.Review, repo repository.Repo, logChan chan<- string) error
• func WriteNewReports(reportsMap map[string][]ci.Report, repo repository.Repo, logChan chan<- string) error
• func WriteNewReviews(reviews []review.Review, repo repository.Repo, logChan chan<- string) error

Variables

var (
	// ErrNoTimestamp is exactly what it sounds like.
	ErrNoTimestamp = errors.New("Github status contained no timestamp")
	// ErrInvalidState is returned when a github repository status has an
	// invalid state.
	ErrInvalidState = errors.New(`Github status state was not "success", "failure", "error", "pending", or null`)
	// ErrInsufficientInfo is returned when not enough information is given
	// to perform a valid conversion.
	ErrInsufficientInfo = errors.New("insufficient data for meaningful conversion")
)

var (
	// ErrInvalidRemoteRepo is returned when a given github repo is missing
	// required information.
	ErrInvalidRemoteRepo = errors.New("github repo requires name and owner login")
)

Functions

func CommentsOverlap

func CommentsOverlap(a, b comment.Comment) bool

CommentsOverlap determines if two review comments are sufficiently similar that one is a good-enough replacement for the other.

The purpose of this method is to account for the semantic differences between the comments on a GitHub pull request and the comments on a git-appraise review.

More specifically, GitHub issue comments roughly correspond to git-appraise review-level comments, and GitHub pull request comments roughly correspond to git-appraise line-level comments, but with the following differences:

1. None of the GitHub comments can have a parent, but any of the git-appraise ones can.
2. The author and timestamp of a GitHub comment is based on the call to the API, so if we want to mirror a comment from git-appraise into GitHub, then when we read that new comment back out this metadata will be different.
3. Review-level comments in git-appraise can have a specificed commit, but issue comments can not.
4. File-level comments in git-appraise have no corresponding equivalent in GitHub.
5. Line-level comments in GitHub have to be anchored in part of the diff, while in git-appraise they can occur anywhere within the file.

To work around these issues, we build in the following leeway: 1. We treat two comment descriptions as equivalent if one looks like a quote of the other. 2. We treat two locations as equivalent if one of the following holds:

0. They actually are the same
1. Both are review-level comments, and one of them does not have a commit set
2. They are either file-level or line-level comments and occur in the same file

This definition of equivalence does allow some information to be lost when converting from one format to the other, but the important information (who said what) gets maintained and we avoid accidentally mirroring the same comment back and forth multiple times.

func ConvertDiffComment

func ConvertDiffComment(diffComment *github.PullRequestComment) (*comment.Comment, error)

ConvertDiffComment converts a comment on the diff associated with a pull request into a git-appraise review comment.

func ConvertIssueComment

func ConvertIssueComment(issueComment *github.IssueComment) (*comment.Comment, error)

ConvertIssueComment converts a comment on the issue associated with a pull request into a git-appraise review comment.

func ConvertPullRequest

func ConvertPullRequest(pr *github.PullRequest) (*request.Request, error)

ConvertPullRequest converts a pull request fetched from the GitHub API into a review request.

func ConvertPullRequestToReview

func ConvertPullRequestToReview(pr *github.PullRequest, issueComments []*github.IssueComment, diffComments []*github.PullRequestComment, repo repository.Repo) (*review.Review, error)

ConvertPullRequestToReview converts a pull request from the GitHub API into a git-appraise review.

Since the GitHub API returns pull request data in three different places (the PullRequest object, the list of comments on the corresponding issue, and the list of diff comments), all three must be supplied.

This method requires a local clone of the repository in order to compute the locations of the different commits in the review.

func ConvertStatus

func ConvertStatus(repoStatus *github.RepoStatus) (*ci.Report, error)

ConvertStatus converts a commit status fetched from the GitHub API into a CI report.

func ConvertTime

func ConvertTime(t time.Time) string

ConvertTime converts a Time instance into the serialized string used in the git-appraise JSON formats.

func GetAllPullRequests

func GetAllPullRequests(local repository.Repo, remoteUser, remoteRepo string, client *github.Client, errOutput chan<- error) ([]review.Review, error)

GetAllPullRequests reads all of the pull requests from the given repository. It returns successful conversions and encountered errors in a channel. Errors processing individual channels will be passed through the supplied error channel; errors that prevent all processing will be returned directly.

func GetAllStatuses

func GetAllStatuses(remoteUser, remoteRepo string, client *github.Client, errOutput chan<- error) (map[string][]ci.Report, error)

GetAllStatuses iterates through all of the head commits in the remote repository, reads their statuses from Github, and returns the git-appraise equivalents.

Errors processing individual channels will be passed through the supplied error channel; errors that prevent all processing will be returned directly.

func RequestsOverlap

func RequestsOverlap(a, b request.Request) bool

RequestsOverlap determines if two review requests are sufficiently similar that one is a good-enough replacement for the other.

The purpose of this method is to account for the semantic differences between a GitHub pull request and a git-appraise request. More specifically, a GitHub pull request can only have a single "assignee", but a git-appraise review can have multiple reviewers. As such, when we compare two requests to see if they are "close enough", we ignore the reviewers field.

func WriteNewComments

func WriteNewComments(r review.Review, repo repository.Repo, logChan chan<- string) error

WriteNewComments takes a list of review comments read from GitHub, and writes to the repo any that are new.

The passed in logChan variable is used as our intermediary for logging, and allows us to use the same logic for logging messages in either our CLI or our App Engine apps, even though the two have different logging frameworks.

func WriteNewReports

func WriteNewReports(reportsMap map[string][]ci.Report, repo repository.Repo, logChan chan<- string) error

WriteNewReports takes a list of CI reports read from GitHub, and writes to the repo any that are new.

The passed in logChan variable is used as our intermediary for logging, and allows us to use the same logic for logging messages in either our CLI or our App Engine apps, even though the two have different logging frameworks.

func WriteNewReviews

func WriteNewReviews(reviews []review.Review, repo repository.Repo, logChan chan<- string) error

WriteNewReviews takes a list of reviews read from GitHub, and writes to the repo any review data that has not already been written to it.

The passed in logChan variable is used as our intermediary for logging, and allows us to use the same logic for logging messages in either our CLI or our App Engine apps, even though the two have different logging frameworks.