Project Description

Summary

This specification will describe a convention on top of a git repository that makes it easier for developers to collaborate.

Open Pull Requests will provide a standard way for reviewing and discussing proposed changes before integrating them into a target branch.

They will be stored inside the repository itself as git references, yet they will not interfere with the rest of the branches.

Goals

To communicate the intent of integrating changes from one branch into another.
To facilitate reviewing, discussing, accepting and rejecting proposed changes.
To allow collaboration from developers who don’t necessarily have write access to the target git repository.
To make the mechanism as compatible as possible with any existing git repository hosting services available.
To make it usable when no hosting service is being used (i.e. a regular git repository shared over SSH), or even when a developer is offline.
To support pull requests over a distributed network of repositories.

Prior Art

There are several well-known git repository hosting services that provide Pull Requests as an additional functionality through their web application.

Our goal here is to look at how do they store internally (in the git repository) information about the pull requests, so that this specification can integrate better with them if possible.

GitHub

For each Pull Request, GitHub exposes the next internal, read-only git references:

refs/pull/:ID/head: points to the head of the source branch of the Pull Request.
refs/pull/:ID/merge: points to a branch that integrates proposed changes into the destination branch (if there are no conflicts).

In addition, other metadata is exposed through the REST API: https://api.github.com/repos/octocat/Hello-World/pulls/32

BitBucket

For each Pull Request, BitBucket exposes the next internal, read-only git references:

refs/pull-requests/:ID/from: points to the head of the source branch of the Pull Request.
refs/pull-requests/:ID/to: points to the head of the destination branch of the Pull Request.
refs/pull-requests/:ID/merge: points to a branch that integrates proposed changes into the destination branch.
refs/pull-requests/:ID/merge-clean: symlink reference to previous /merge reference if there are no conflicts.
refs/pull-requests/:ID/merge-conflicted: symlink reference to previous /merge reference if there are any conflicts.
refs/notes/pull-requests/:ID/merge: contains the list of conflicted files for previous /merge-conflicted reference.

In addition, other metadata is exposed through the REST API: https://api.bitbucket.org/2.0/repositories/tutorials/tutorials.bitbucket.org/pullrequests/4199

GitLab

For each Merge Request, GitLab exposes the next internal, read-only git references:

refs/merge-requests/:ID/head: points to the head of the source branch of the Pull Request.
refs/merge-requests/:ID/merge: points to a branch that integrates proposed changes into the destination branch (if there are no conflicts).

In addition, other metadata is exposed through the REST API: https://gitlab.com/api/v4/projects/8377576/merge_requests/1

Project Description

Summary

Goals

Prior Art

GitHub

BitBucket

GitLab

References

GitHub

BitBucket

GitLab