Feature Update: Patches 🎉

We’re excited to let everyone know that we’ve started to work on implementing patches in Radicle. :tada: Our working name for patches in Radicle is revisions. Revisions will be similar to pull requests (GitHub) and merge requests (GitLab). They will allow contributors to share changesets with maintainers for review and inclusion.

What’s unique about revisions in Radicle is that they are stored locally as git objects. When a remote is followed, their revisions are replicated locally and namespaced in the user’s monorepo as git references. While the minimum viable version of revisions will rely on the client for creation, Radicle users will be able to retrieve, review, and merge patches locally via the command line in the future — a vision similar to that outlined in this post written by Konstantin Ryabitsev of the Linux Foundation.

Since this is by far our most asked for feature, the goal of this version is to get people collaborating ASAP. We’d love feedback on what the community would like to see in future versions of revisions. :seedling: Feel free to drop comments, questions, and feedback here.


Creating Revisions

Anita (contributor) wants to contribute to Val’s (maintainer) project, dictio. Assume that she is already tracking Val’s project and that she has already created and published (pushed to the rad remote) a branch, anita/improve-typography, with a set of commits that she wants Val to merge into the project’s main branch.

When Anita opens the Upstream client and navigates to Val’s project, she sees a button asking her if she would like to Start a revision. Her revision is identified by the name of the branch she published to the rad remote, anita/improve-typography.

Clicking the Start a revision button brings up a modal with a quick overview of the branch: how many commits ahead of main the branch is, lines changed, and a list of the latest commits.

Once she clicks Start revision, the revision is created as a git reference in their monorepo and named after the branch:

refs/namespaces/dictio/refs/rad/revisions/anita/improve-typography

To read more about how we use namespaces in Radicle, check out our documentation.

This revision is then replicated to Val’s monorepo. From here, Anita is brought to the Revisions tab of Val’s project, so she can see the files changed and commit log.

In the Revisions tab, Anita can view all of her revisions and those of any peers she follows. If Val merges Anita’s revision, it will move from the Open tab to the Merged tab.

Updating a Revision

If Anita wants to update her revision, she must commit the changes locally to the branch that contains the revision code and publish it to the network by pushing it to the rad remote. Anita then navigates to her revision. There, she’ll see a banner with a prompt to update the revision. Clicking the Update button will update the revision and announce the changes to Val.

If Val had merged Anita’s revisions before the update was replicated, Anita would receive a notification that she needs to start a new revision.

Maintainer

For each project that Val maintains, there is a list of proposed revisions from other peers in the Revisions tab. She can only view the revisions from tracked peers. If Val wants to, she can Hide revisions in the list. This means that the revision will be removed from the list unless the contributor of the revision updates it.

Reviewing revisions

Val can view Anita’s changes by clicking the revision.

However, until code review is designed into the Upstream client, Val will have to check out Anita’s branch locally to review the proposed changes. She starts the review by clicking Checkout on Anita’s Revision. This will display a set of Git commands for checking out and reviewing the revision locally.

Once Val reviews Anita’s changes, she can merge them locally by following the corresponding Git commands.

Once Val accepts Anita’s revision, it is moved from the Open tab to the Merged tab of the revision list.


Looking forward to hearing your feedback and thoughts :seedling:

14 Likes

Hi @abbey,

I just read this post and took away, that revision creators need to track the maintainer repo in order to create revisions, and that maintainers need to track revision creators in order to ‘receive’ revisions.

Are there any plans or ideas on making possible contributions of untracked peers discoverable?

Hey @mkroehnert and welcome!

Yes, there are definitely plans for this! In fact, this might even be part of the first MVP release if it is not very hard to implement. (What helps us here is the fact that a node will most likely be connected to our seed node which would serve as a pub to make revision available to everybody.)

1 Like

Nice!!! a lot of work has been done. excellent result!

Since it’s been a while since this was posted I wanted to give everybody an update on the progress of this.

First of all, after some feedback that the term “revision” is ambiguous we are using the term “merge request” for now.

While working on the technical design for merge request we came to the conclusion that Git tags properly serve as the based base for this feature. While we had to scrap some of our earlier work this also created some opportunities for merge requests.

The main change coming from the use of tags is that we can now leverage the Git CLI for creating, updating, and checking out merge requests. To keep us focused on the hard problems (p2p etc.) we will drop creation, updates, and check outs from the GUI and replace them with instructions how to do it in the terminal. This does not mean that we don’t have the intention of building these but the first release will likely come without them.

One of the reasons why we chose tags is also that tags can be annotated. This effectively provides a way for us to add merge requests titles and descriptions for merge requests. This should make the feature much more useful.

While tags are the right underpinning for this feature we had to spend a lot of time during the last couple of weeks to prepare the underlying protocol for their use. (You might have noticed that while upstream supports branches at the moment it does not support tags and there’s a reason for that.) On challenge was that Git treats tags differently than other refs: they are basically global, which, as you can imagine, can create some problems in a fully decentralized setup.

At the moment we have a working proof-of-concept of this feature and we’re starting to polish some of the code and UI. But there are also still some bugs in the replication that might be harder to fix that we are looking into. You can follow the progress on this branch. And if you’re feeling adventurous you can also try it out.

8 Likes

I would like to give a brief update regarding the name of this feature. When we announced the feature we got some feedback on Matrix that the term “revision” is confusing because it is a technical term within Git with a conflicting meaning. (We borrowed the term from Phabricator.)

After this feedback a group of us started thinking about alternatives and, after some back and forth, landed on the term “patch”. While the term in its narrow technical meaning does not quite match what we are building, we feel that is used liberally enough in the OSS community to not cause confusion. We also believe that the wider meaning of “patch” best conveys the core of the feature: sharing code changes with the wider community.

As always, we would love to hear any feedback on this!

4 Likes