Need to provide a baseline specification

[yookoala]

The baseline specification would need to support:

• Pull Request
• Forking

Which implies specification to the Actors involve:

• Person
• Repository
• Branch

Terms

Git Service: Web based Git service like Gogs, Gitea, Gitlab, Pagure.
Web Repository: Web based entity on a Git Service that represents an underlying Git repository branch.
upstream: A git repository where a PR is being sent TO.
downstream: A git repository where a PR is being sent FROM.

Features

For federation, these are the base line features:

1. Allow user to create a Pull Request to a remote upstream Web Repository.
2. Allow an upstream Web Repository to receive a Pull Request from a downstream Web Repository.
3. Allow a downstream Web Repository to report updates (e.g. git push) of a branch to an upstream Web Repository that it previously sent Pull Request to.
4. Allow an upstream Web Repository to notify a remote Git Service that a Pull Request is commented, tagged, assigned, reviewed, closed, re-openned or otherwise updated.
5. Allow user to create a Fork notification to a remote upstream Web Repository.
6. Allow an upstream Web Repository to receive a Fork notification from a downstream Web Repository (not branch specific).
7. Allow any agent to subscribe to any Web Repository updates.

Based on these feature needs, It might also be essential to allow any Web Repository (specific branch) to be properly addressable and discover-able by query protocol (e.g. Like how Mastodon use Web Finger). This universal address should be differ from user or organization.

Related Issues

There are several issues in different software repository of the same topic:

• Federation between gogs instances gogs/gogs#4437
• Federation for organization, repositories and users go-gitea/gitea#1612
• https://gitlab.com/gitlab-org/gitlab-ee/issues/4517

[yookoala]

@cwebber: It would be great if you can give some advice on the approach and even co-edit the future specification. Please help.

[bill-auger]

someone from peers just noticed this - i would like to mention that some members of the peers community have been working on this for some time - there was a very similar design document/RFC written last year in which members of the gitea and pagure projects have expressed interest - you read that at this URL:

https://notabug.org/NotABug.org/notabug-2.0

work has been done on two competing reference implementations - the most mature of which ('vervis') is nearly at the demo stage - it's federation mechanism is based on activity-pub and JSON-LD so vervis probably already meets or exceeds the requirements declared in this repo

above all though, i would expect that this project, if proposed with any sincerity as a formal working group, should offer some real contact information, such as a proper mailing list - to insist that all communication take place on github is quite ironic in this context

[yookoala]

@bill-auger: Thanks for the input. It is exciting to see that there is already an effort for such a thing, especially when it is very close to how I imagine such protocol to be. It would be great to learn the current specification and implementations.

As for a formal work group, please join the discussion in #5. Thanks.

[bill-auger]

i will try to put you in touch with the developers - i can not overstate the fact that there would be significantly less friction attracting the sort of people who care the most about this issue if it were not hosted exclusively on github

[yookoala]

@bill-auger: Thanks. Once there are developers of different git web services here, we can discuss where to move to. And we should.

[bill-auger]

in that case, i would be remiss not to mention my personal favorite git hosting platform 'pagure' - that is a glaring omission in the examples ive seen on this repo - i should ping @pypingou (the pagure lead developer) to this discussion

if you would like another example of existing discussions, you could add this pagure discussion on federation to the "related issues" in the OP
https://pagure.io/pagure/issue/2335

as well the notabug-2.0 document i mentioned earlier - though that is not itself a discussion, it is an entire repo with issues related to individual features - the README itself is the product of many days worth of discussion on IRC
https://notabug.org/NotABug.org/notabug-2.0

[pypingou]

/me is lurking around already since yesterday ;-)

But thanks for the ping nonetheless :)

[o01eg]

Is it required to use forks? I've seen Pijul Nest doesn't use them: https://nest.pijul.com/pijul_org/pijul

Create a new discussion on the Nest, to gather feedback on your proposal.
Make your change, record a patch
Push it to the Nest. You do not need to create a fork on the Nest, as you would on GitHub for instance, to propose a change. You can actually “push your change” directly to the discussion. When you created your discussion, it got assigned a number. If this number is, for instance, 271, then you can propose a change by pushing to the branch #272, just like that:

[yookoala]

@o01eg: I don't think fork is required, per se, for any service. But it happens to be what most git service is providing. When I wrote the first post here, I wanted to make sure that the usual development experience can be reserved by an open standard. I think it is entirely OK for some implementation to leave out the Fork part and only for PR.

In the development cycle with git services, a developer usually Fork a repository as a downstream. Then when they have something they wanted to share, they would send a PR to upstream. This Fork-PR cycle has made familiar by Github, Gitlab or Bitbucket over the years. And it has definitely made things easier for developers.

IMO, the key to the "Fork experience" is for downstream repositories to somehow pass their updates back to upstream so it might somehow display them (e.g. the fork count, fork graph). Without such ping-back mechanism, Fork is simply a silence git clone on server side.

Of course, it is simply my opinion. I do not insist.

[o01eg]

As I know servers don't do git clone because it require space for two mostly identical repositories. Servers use the same repository and manages different people via branches.

[jaywink]

How servers handle the git stuff is IMHO implementation details of server itself. How I see this work (a protocol for communicating between servers) is creating a common (ActivityPub based) language for servers to talk to each other.

An example (just throwing ideas here). User "Bob" on a GitLab server might fork a repository of user "Alice" whose repository is on a Gitea server. Bob's server delivers a payload something like this (mostly copied from AP examples:

{"@context": "https://www.w3.org/ns/activitystreams",
 "type": "Create",
 "id": "https://bob.tld/activities/a29a6843-9feb-4c74-a7f7-081b9c9201d3",
 "to": ["https://alice.tld/users/alice"],
 "actor": "https://bob.tld/users/bob,
 "object": {"type": "Fork",
            "id": "https://bob.tld/repos/awesomecoolthing",
            "origin": "https://alice.tld/repos/awesomecoolthing",
            "to": ["https://alice.tld/users/alice"]}}

Alice will now be aware that a Fork has been done and who it was done by and where it is located. They will probably want to automatically follow it for updates. Of course, Alice can just ignore the Fork payload and live happily.

But what happens with git is IMHO totally irrelevant and implementation detail of the server itself. To actually make things useful, Bob's server will probably clone the code from Alice's repo - but this has IMHO nothing to do with ActivityPub or federation - it's "just git things".

[bill-auger]

generally in federation, nothing is strictly required - each implementation is free to expose as many of few parts of the spec as it chooses

the notion of a "fork" in the context of git is purely logical - it has no real semantics other than "this repo has some commits in common with some other repo" - the fact that hosts may display one replica as the base and others as child forks is actually quite against the grains of how git was designed to be used - all git repos are first-class; and all git repos with the same commits have by nature, identical code trees and commit histories - considering one to be the master and another to be a fork is completely optional and not meaningful to or even representable in git itself

that being said, most people probably expect that to be presented on the GUI as to give the original poster primary credit for the work; so there is not reason not to have it in the spec as an optional message - o/c the inherent flaw should be obvious in the presumption that whoever posts the code first deserves primary credit but people will want this feature nonetheless

the concept of a fork is not required to send merge requests - patches can flow downstream as well as upstream - that distinction does not actually exist - the minimum requirement for a merge request is a destination repo URL, a destination branch name, and the patch to apply

[bill-auger]

the mailing list is now fully functional - a thread has been started on the mailing list to continue the discussion of the baseline spec - for those who are subscribed to the mailing list, check your email for the thread titled "scope of the workgroup goals"; and reply to it to continue the discussion begun on this issue

[ppwfx]

I personally like to conceptualise by writing code. That's why quickly build a low level library in golang. It allows you compose, decode and encode ActivityPub objects.

Next Im going to build a lite microservice, implementing the basic ActivityPub endpoints.
That allows to tinker around with the communication layer and to extend it with the git specific types.

https://github.com/21stio/go-ap

[rugk]

BTW the OP misses GitHub in this list:

Git Service: Web based Git service like Gogs, Gitea, Gitlab.

[yookoala]

BTW the OP misses GitHub in this list

I'ld love to have GitHub joining the list. But I doubt the likeliness.

Maybe we'll add the name if GitHub staff joined our discussion :-)

[pypingou]

pagure is for sure missing ;-)

[yookoala]

pagure is for sure missing ;-)

You're right. Just added :-)

[Arkanosis]

pagure is for sure missing ;-) You're right. Just added :-)

I'd add phabricator as well (which is interesting, because it's not limited to git, but also handles Mercurial and SVN).

[yookoala]

@Arkanosis: I believe I would have missed a lot of them. Let's make a rule here: "If a contributor from a Git service software has joined our mailing list, I'd add the name here"

Sounds right?

[Arkanosis]

Sounds right, thanks :)