As most of you probably know, we're working on a pull requests implementation for Tangled. The primary goal isn't to simply reimplement what GitHub has done for well over a decade—but to improve on the status quo, while making sure there's still familiarity to the whole flow. Keeping that in mind, we're introducing two kinds of pull requests.
- PRs v1 (patch requests)
- PRs v2 (submissions)
pull requests v1 (patch requests)#
This is the first version of pull requests that we will launch. This follows a very simple model and serves to encourage smaller, "driveby" contributions. Here's how it would work:
- Clone the repository you'd like to contribute to.
- Make your change and commit it. You can do this on the main branch.
- Run
git format-patch -1 HEAD --stdout. You may either pipe this to your clipboard program (pbcopy, wl-clip, ...) or simply copy the output from your terminal. - Head to the repository on Tangled and create a new pull request from the "pulls" tab.
- Fill out your title and description of your change, and paste the
git format-patchoutput in the provided textbox. - Submit, and edit later as per review.
Optionally, this can be extended to more than 1 commit (pass in -2, -3, and so on) and paste the resulting patch series into the textbox. This is of course, a very simple model that only facilitates smaller changes that can typically fit within a few small commits. However, we see this as a driver for contributions that probably would not have happened in the traditional flow simply due to the overhead involved.
pull requests v2 (submissions)#
This workflow blends the more familiar GitHub PR model with changeset-oriented reviewing by allowing developers to work in feature branches and submit consolidated changes for review. This is what it would look like:
- branch-based development
- Developer creates and pushes to a feature branch as their working area
- Multiple incremental commits can be made during development
- PR Submission
- When ready for review, developer initiates a "PR Submission"
- System automatically squashes all branch commits into a single commit
- Developer is prompted to provide a title and detailed description (which becomes the commit message)
- review process
- Reviewers examine the consolidated changes in the submission
- Feedback is provided on the squashed commit
- iteration
- Developer makes additional changes to their feature branch based on feedback
- When changes are complete, they "resubmit" the PR, updating the commit message if necessary
- System creates a new squashed commit with updated changes, replacing the existing one.
- finalization
- Once approved, the squashed commit can be merged to the main branch
This approach maintains a clean history in the main branch while still allowing developers flexibility in their working branches.
meta notes#
These changes heavily depend on knots supporting the new /:did/:repo/merge and /:did/:repo/merge/check endpoints. To identify whether a knot supports pull requests—and subsequent features like search, code navigation, … etc. in the future, we're planning to introduce a capability model.
This could look something like knot.example.com/meta/capabiities which returns a map of features and their versions. For instance:
{
"pull_requests": "v2",
"code_search": "v1",
"foo_bar": "v3",
}
This then allows the appview to conditionally enable operations and/or disable certain functionality on repositories hosted on knots that don't support them.
v2.2.2: There whould be three options (like on GitHub):