This thread picks up from another, which drifted well off its original topic.

This feature request has come up many times before: [0] [1] [2] [3]

I want to concentrate all of that prior thought and crystalize it. I think we'll soon be in a very good position to finally move on this. If it turns out that we can't get this soon, this forum thread will at least provide a central resource to point people at when they inevitably ask for such a feature yet again.

The Wish

We want something like GitHub pull requests in Fossil, but we don't want to turn Fossil into Git or GitHub to get it.

Terminology

The term "pull request" implies either:

• A centralized service like GitHub, where all of the involved repositories are held within that single service, so that one repo can pull directly from another. I don't think we can expect Fossil to evolve in this direction: if it did, it would fork Fossil into two very different VCSes. Fossil is a true DVCS, and many of us like it that way.

• Both the sending and receiving Fossil repos are public, and at least one user of each repo has access to the other. That results in a federated model of development like that of the Linux kernel. I don't think we want to require such a setup just to get some variation on GitHub pull requests. (This is how git pull-request works, by the way.)

We don't have to accept the problems with either of these. We just have to flip it around, and it becomes easier to solve while ending up scarcely more difficult to use than GitHub pull requests.

I want to call our alternative a "push request," because it emphasizes the fact that there is an important difference in outlook between Fossil and Git/GitHub.

Others have called this a merge request instead.

Unprivileged Workflow

An outside contributor does their work on a branch in a clone of the central repository, which was made as a Fossil user without checkin rights. Some of the methods below even allow anonymous clones. The outside contributor should disable autosync on that clone's checkout so that all checkins go into the local clone repo only without taking time to repeatedly fail on sync.

When the outside contributor is ready to push their change up to the central repo, they say something like:

  $ fossil bundle push --branch my-new-feature

And Then What Happens?

We have many possible ways to go from there, all well within our reach:

1. Append Unversioned — This is a new capability (I propose U) which the central repo's admin assigns to users on request. It allows remote Fossils to upload a bundle to the central repository without also granting them the ability to delete or replace existing unversioned files, as the current Write Unversioned capability (u) allows.

   (I do not recommend giving this capability to nobody, since that would allow spam in quantities sufficient to DoS the central server. I also do not recommend giving it to anonymous since the CAPTCHA mechanism only works via Fossil UI, and we don't want to require push requests via the central repo's web UI only. Separately, the central repo's admin will likely wish to have the option to revoke this capability from an individual user who abuses their privilege, so the privilege must be granted on a per-user basis anyway.)

   The outside contributor's Fossil instance uploads the bundle using a special naming convention (e.g. pr-bundle-abcd1234efg...) that causes the central repo to notify interested parties of a new push request. Someone with checkin rights on the central repo could then say:

     $ fossil bundle import --uv abcd1234
   

   That syntax would make fossil bundle look for the bundle in the unversioned file table, not the local filesystem. The argument is a unique prefix of the hash part of the unversioned artifact's name. It could also be a prefix of the blob ID or the file's SHA-1 hash.

   If the committer likes the push request, she can then say:

     $ fossil bundle import --uv abcd1234 --publish
   

   to merge it into the central repo.

2. Push to Forum — On bundle push, the outside contributor's Fossil instance opens a text editor for a forum post, just as for composing a checkin comment. That then pushes the bundle to the remote Fossil instance, making use of the existing attachment mechanism to hold the bundle. The central repo's admin then needs to grant only Write Forum permission to the user doing the push request.

   (Implicitly, this means the current forum feature needs to allow file attachments. Again, the underlying mechanism already exists, someone just needs to enhance the Fossil forum feature to make use of it.)

   The committer then says:

     $ fossil bundle import --forum abcd1234
   

   and all proceeds as before.

   By doing this through the forum, others can comment on the push request before it's merged. (And after, of course.)

   This method gets you most of the way toward another oft-requested feature: code reviews. It might be close enough as presented here for some users.

   The easy way to work this is for the central repo to be the same as the forum repo, but in cases like the current fossil-scm.org one, we can add a CLI option to cope:

     $ fossil bundle import --forum abcd1234 -L ~/museum/fossil-forum.fossil
   

   or

     $ fossil bundle import --forum abcd1234 -L ../forum
   

   The -L flag gives the path to the Local forum repo clone or to one of its checkouts. It is named by analogy to -L and -R in OpenSSH, with the mnemonic changing from R=repo to R=remote repo.

3. Push as Ticket — This method has some workflow and cosmetic advantages over doing it via the forum.

   The command differs only trivially:

     $ fossil bundle import --ticket abcd1234
   

   That will pop up a ticket submission template in the submitter's text editor. It could have predefined fields for the key user-supplied ticket fields: summary line, severity, subsystem, etc.

   For fields presented in Fossil UI as drop-downs, if the submission uses text that doesn't match one of the predefined fields, the receiving Fossil instance should probably just drop the text rather than insert the text as given, since that would screw up existing ticket reports. The ticket triager can fix it up, since they're likely to need to make other edits to the ticket anyway.

4. Push via Email — The outside contributor configures their local Fossil with their local email setup via global settings, allowing bundle push to send the bundle off as an attachment to an email message. The email goes to an address configured on the central clone, like fossil-bundles@example.com, which is a bit of new metadata that comes down with the clone.

   The major advantage of this option is that it doesn't require that the central repo give out a user capabilities before it can accept a push request. The remote user also doesn't have to re-sync using a user account, which they might need to set up before they can commit, which adds friction to the process, increasing the likelihood that your new committer will give up before getting the contribution to you.

   One disadvantage is that this method is easily spammable, unlike the prior options.

   This might be a more popular use of the direct-to-SMTP email method than on central Fossil servers, since central Fossil servers often run on machines that already need a sendmail type setup of some kind, so that's the low-friction path.

5. Push to Custom HTTP Endpoint — The above methods have the advantage of reusing existing mechanisms, but what if the central repository doesn't want to give out the capability bits or open the services required? Maybe they'd prefer to reserve those for other purposes, and would welcome a method to control this push request separately.

   Fossil could offer a /push service, which would accept an HTTP POST from the outside contributor's Fossil instance, gated by a new user capability. Call it Push Request. I propose using capability letter P for this.

"Bundle Push"?

There are other ideas for the exact Fossil command the submitter gives.

I think bundle push is consistent with the existing bundle feature set, but perhaps it focuses too much on the mechanism. It might also be nice to have a clear sub-command show up in fossil help output, rather than hide it behind bundle.

Another idea I haven't seen before is to extend fossil push:

  $ fossil push --branch my-new-feature
  $ fossil push --branch my-new-feature -L ../forum
  $ fossil push --branch my-new-feature -L ~/museum/fossil-forum.fossil

The first pushes to a forum-and-code repo, and the latter two are as above, for use with separate forum and code repos.

I like extending the push verb because in an outside contribution model, autosync is likely to be disabled on outsiders' checkouts, so an explicit push is a more useful concept than when direct commits are allowed.

Multiple Methods?

We don't necessarily have to pick only one of the methods above. We might like to have several options available. The push command would accept the same flags as in the bundle import examples above:

  $ fossil bundle push --branch my-new-feature --ticket
  $ fossil bundle push --branch my-new-feature --email fred@example.com
  $ fossil bundle push --branch my-new-feature --forum -L ../forum

The bundle import method must match the bundle push method, of course.

Fossil UI Integration

I've given all of the above in terms of the CLI, but some of the methods allow for Fossil UI integration: push via /uv, forum, and ticket, in particular. Push via custom HTTP endpoint could also work with this, though it would require new UI work.

For the most part, I think the central repo's committer wants to work at the command line for this, since they're going to need to build and test the contribution before accepting it anyway.

However, there are some small advantages of doing the actual PR acceptance in the GUI, basically amounting to closing the feedback loop:

• Delete the /uv artifact.
• Reply "Merged, thanks!" to a commit-by-forum PR
• Comment similarly on a commit-by-ticket PR and close the ticket.

It is possible that some pushes are so obvious that they could be inspected purely in Fossil UI and accepted right there. A common example would be a typo fix in the project docs or in a source code comment.

Private Branches

None of the above requires use of private branches. You can do it that way if you like, but it'll work with un-sync'd "public" branches, too. Using private branches instead is just a small workflow enhancement to avoid "not authorized to push" complaints from Fossil.