ForgeFed

ForgeFed Modeling - draft - 2019-11-12 master 17885ce

1 Abstract

This document describes the rules and guidelines for representing version control and project management related objects as linked data, using the ForgeFed vocabulary, ActivityStreams 2, and other related vocabularies.

2 Introduction

The ForgeFed modeling specification is a set of rules and guidelines which describe version control repository and project management related objects and properties, and specify how to represent them as JSON-LD objects (and linked data in general) using the ForgeFed vocabulary and related vocabularies and ontologies. Using these modeling rules consistently across implementations and instances allows to have a common language spoken across networks of software forges, project management apps and more.

The ForgeFed vocabulary specification defines a dedicated vocabulary of forge-related terms, and the modeling specification uses these terms, along with terms that already exist in ActivityPub or elsewhere and can be reused for forge federation.

The ForgeFed behavior specification provides instructions for using Activities, and which Activities and properties to use, to represent forge events, and describes the side-effects these Activities should have. The objects used as inputs and outputs of behavior descriptions there are defined here in the modeling specification.

3 Commit

To represent a named set of changes committed into a repository’s history, use the ForgeFed Commit type. Such a committed change set is called e.g. a commit in Git, and a patch in Darcs.

Properties:

Example:

{
          "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://forgefed.peers.community/ns"
          ],
          "id": "https://example.dev/alice/myrepo/commits/109ec9a09c7df7fec775d2ba0b9d466e5643ec8c",
          "type": "Commit",
          "context": "https://example.dev/alice/myrepo",
          "attributedTo": "https://example.dev/bob",
          "created": "2019-07-11T12:34:56Z",
          "committedBy": "https://example.dev/alice",
          "committed": "2019-07-26T23:45:01Z",
          "hash": "109ec9a09c7df7fec775d2ba0b9d466e5643ec8c",
          "name": "Add an installation script, fixes issue #89",
          "description": {
              "mediaType": "text/plain",
              "content": "It's about time people can install it on their computers!"
          }
      }

4 Branch

To represent a repository branch, use the ForgeFed Branch type. It can be a real built-in version control system branch (such as a Git branch) or a copy of the repo used as a branch (e.g. in Darcs, which doesn’t implement branches, and the way to have branches is to keep multiple versions of the repo).

Properties:

Example:

{
          "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://forgefed.peers.community/ns"
          ],
          "id": "https://example.dev/luke/myrepo/branches/master",
          "type": "Branch",
          "context": "https://example.dev/luke/myrepo",
          "name": "master",
          "ref": "refs/heads/master"
      }

5 Repository

To represent a version control repository, use the ForgeFed Repository type.

Properties:

Example:

{
          "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://w3id.org/security/v1",
              "https://forgefed.peers.community/ns"
          ],
          "id": "https://dev.example/aviva/treesim",
          "type": "Repository",
          "publicKey": {
              "id": "https://dev.example/aviva/treesim#main-key",
              "owner": "https://dev.example/aviva/treesim",
              "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhki....."
          },
          "inbox": "https://dev.example/aviva/treesim/inbox",
          "outbox": "https://dev.example/aviva/treesim/outbox",
          "followers": "https://dev.example/aviva/treesim/followers",
          "team": "https://dev.example/aviva/treesim/team",
          "name": "Tree Growth 3D Simulation",
          "summary": "<p>Tree growth 3D simulator for my nature exploration game</p>"
      }

6 Pushing Commits into a Repository

TODO

7 Ticket

TODO