We’re excited to let everyone know that we’ve started to work on implementing patches in Radicle. 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. 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