Namespaces, vocab extensions and domain separation #158

New Issue

Open

opened 2022-08-19 09:19:49 +00:00 by circlebuilder · 2 comments

circlebuilder commented

2022-08-19 09:19:49 +00:00

I highlighted several parts of the ForgeFed description on the landing page forgefed.org:

ForgeFed is an upcoming federation protocol for enabling interoperability between version control services. It’s built as an extension to the ActivityPub protocol, allowing users of any ForgeFed-compliant service to interact with the repositories hosted on other instances.

The goal of the project is to support all of the major activities connected to project management, including bug reports, merge requests, and notifications across instances.

This issue is related to an earlier thread on the forgefriends forum: Repositioning ForgeFed? Scope to Code Forges or Free Software Development Lifecycle (FSDL). At the end of this thread I note that ForgeFed itself need not reposition, but that realizing that it is part of a larger whole (the FSDL) is beneficial (and that an ecosystem alliance forg.es may take on a larger scope).

But still I'd like to make a related remark. The highlighted texts are indicators that we deal with different bounded contexts to speak in domain-driven design terms. They might indicate a bunch of sub-domains.

Core domains:

Revision Control (commits, versions, tags)
Code Review (merge requests)
Project Management (projects, boards)
Issue Management (bug reports)

Supporting subdomains:

User Management (users, profiles)
Auth / Authz (OCAP?, Grants?)

Generic subdomains:

Notifications

(The names of these domains, and the ways they are split is not relevant here. This is just an example)

My observation is that:

ForgeFed is defining all these bounded contexts in a single namespace.
What's included is derived by finding the common denominator of multiple forge softwares.
Risk is that ForgeFed specs start to represent more of an application model than concrete and separate 'business domains' (i.e. different software development activities).

Considerations:

Shouldn't specs be split up according to business domains?
- So they can evolve independently of each other.
- So they can be implemented independently of each other.
Have different namespaces, separate vocab extensions (JSON-LD contexts)
- Some of these subdomains have broader applicability even beyond ForgeFed.
- For example #149 User migration (the Move mechanism).
- For example OCAP (with Grant and fullfills).
Version the specs per namespace / vocab extension separately as well.

I highlighted several parts of the ForgeFed description on the landing page [forgefed.org](https://forgefed.org): > ForgeFed is an upcoming federation protocol for enabling interoperability between **version control** services. It’s built as an extension to the ActivityPub protocol, allowing **users** of any ForgeFed-compliant service to interact with the repositories hosted on other instances. > >The goal of the project is to support all of the major activities connected to **project management**, including **bug reports**, **merge requests**, and **notifications** across instances. This issue is related to an earlier thread on the forgefriends forum: [Repositioning ForgeFed? Scope to Code Forges or Free Software Development Lifecycle (FSDL)](https://forum.forgefriends.org/t/repositioning-forgefed-scope-to-code-forges-or-free-software-development-lifecycle-fsdl/713). At the end of this thread I note that ForgeFed itself need not reposition, but that realizing that it is part of a larger whole (the FSDL) is beneficial (and that an ecosystem alliance `forg.es` may take on a larger scope). But still I'd like to make a related remark. The highlighted texts are indicators that we deal with different _bounded contexts_ to speak in domain-driven design terms. They might indicate a bunch of sub-domains. Core domains: - Revision Control (commits, versions, tags) - Code Review (merge requests) - Project Management (projects, boards) - Issue Management (bug reports) Supporting subdomains: - User Management (users, profiles) - Auth / Authz (OCAP?, Grants?) Generic subdomains: - Notifications (The names of these domains, and the ways they are split is not relevant here. This is just an example) My observation is that: - ForgeFed is defining all these bounded contexts in a single namespace. - What's included is derived by finding the common denominator of multiple forge softwares. - Risk is that ForgeFed specs start to represent more of an application model than concrete and separate 'business domains' (i.e. different software development activities). Considerations: - Shouldn't specs be split up according to business domains? - So they can evolve independently of each other. - So they can be implemented independently of each other. - Have different namespaces, separate vocab extensions (JSON-LD contexts) - Some of these subdomains have broader applicability even beyond ForgeFed. - For example #149 User migration (the `Move` mechanism). - For example OCAP (with `Grant` and `fullfills`). - Version the specs per namespace / vocab extension separately as well.

fr33domlover commented

2022-08-21 12:06:10 +00:00

Owner

The core domains

CUrrently, ForgeFed is indeed handling them together in a single specification. That's because they're very related. For example:

It doesn't make much sense for a commit and a patch to use different vocabulary, because they're essentially the same thing (a commit is a patch that is committed into the repo's history; while a patch is perhaps just an offer that isn't committed/merged yet)
It doesn't make much sense for issues and PRs to use entirely separate vocabularies because the whole work-item-related aspect is something they share (assignees, due date, tags, milestone, comments, time tracking, priority, dependent tasks, related commits, mentions in other issues/PRs...)
The features and formats of patches and merge requests are related to the type of VCS and other features of the repo against which they're made

It may be possible to separate the spec into multiple layers, e.g. have a spec with work-item-related stuff, and on top of that a spec for issue tracking and a spec for merge requests. But keeping tracking of these layers and their dependencies would create manual cumbersome extra work, especially because the vocabulary isn't stable yet and can go through big changes. It's much, much easier to prototype with all the toys and tools in one basket, and consider if/how to split them later, when it's clear what depends on what.

The subdomains

These can probably easily get their own specs. ForgeFed now defines a Grant activity because there's no existing standard for S2S OCAPs yet. But eventually there will be, and it will have its own spec.

Bottom line

Perhaps the text at forgefed.org is misleading then?

I recently rewrote the README.md file and probably going to move most of it into the website's homepage, which will hopefully clarify things. But you're very welcome to suggest (via comment or PR) clarifications to the website text!

# The core domains CUrrently, ForgeFed is indeed handling them together in a single specification. That's because they're very related. For example: - It doesn't make much sense for a commit and a patch to use different vocabulary, because they're essentially the same thing (a commit is a patch that is committed into the repo's history; while a patch is perhaps just an offer that isn't committed/merged yet) - It doesn't make much sense for issues and PRs to use entirely separate vocabularies because the whole work-item-related aspect is something they share (assignees, due date, tags, milestone, comments, time tracking, priority, dependent tasks, related commits, mentions in other issues/PRs...) - The features and formats of patches and merge requests are related to the type of VCS and other features of the repo against which they're made It may be possible to separate the spec into multiple layers, e.g. have a spec with work-item-related stuff, and on top of that a spec for issue tracking and a spec for merge requests. But keeping tracking of these layers and their dependencies would create manual cumbersome extra work, especially because the vocabulary isn't stable yet and can go through big changes. It's much, much easier to prototype with all the toys and tools in one basket, and consider if/how to split them *later*, when it's clear what depends on what. # The subdomains These can probably easily get their own specs. ForgeFed now defines a `Grant` activity because there's no existing standard for S2S OCAPs yet. But eventually there will be, and it will have its own spec. # Bottom line Perhaps the text at forgefed.org is misleading then? I recently rewrote the README.md file and probably going to move most of it into the website's homepage, which will hopefully clarify things. But you're very welcome to suggest (via comment or PR) clarifications to the website text!

fr33domlover added the

Core Spec Decision

label 2022-08-21 12:07:18 +00:00

circlebuilder commented

2022-08-22 06:59:59 +00:00

Poster

Perhaps the text at forgefed.org is misleading then?

This is the key point, as it relates to what ForgeFed wants to be.

Because I want discussion here not to be overly long, and more practical outcomes are best tracked here, I have posted a reaction to Discuss Social Coding "ForgeFed versus FSDL: How do they relate?" with links to prior discussion, key considerations and open questions.

> Perhaps the text at forgefed.org is misleading then? This is the key point, as it relates to what ForgeFed wants to be. Because I want discussion here not to be overly long, and more practical outcomes are best tracked here, I have posted a reaction to Discuss Social Coding ["ForgeFed versus FSDL: How do they relate?"](https://discuss.coding.social/t/forgefed-versus-fsdl-how-do-they-relate/127) with links to prior discussion, key considerations and open questions.