Anvil - Federated Forge Client ============================== *CC0 by fr33domlover & ikomi* ## Overview **Vision**: A federated network of forge websites and software development related services and tools, conceptually and practically forming together one big decentralized software project collaboration platform, whose UX/UI/interaction design and features are geared towards filling human needs. **Purpose**: To design and implement a graphical web/desktop client program allowing people to manage, interact and collaborate on software projects, serving as people's portal into the forge fediverse. **Target audience**: Everyone in the software development and deployment lifecycle, emphasis on FLOSS & decentralized software **Values and principles**: - Software freedom - Localization - Integration: - No brand attention, people don't even have to know the software is called Anvil, what matters is the actual features - Desktop notifications - If relevant, split between the UI widget set and the actual implementation logic/models, to allow alternative UIs - Dashboard providing overview of your projects, notifications etc. + project search/exploration/community view - Community: - Be friendly to non-programmers, e.g. people wanting to report a bug - Support collaboration between designers and developers - Perhaps adapt UI to the kind of task? e.g. hide code related stuff for someone who's just translating UI strings - Not tied to any specific VCS or workflow - Distributed network mindset, no emphasis on servers and their names - Not tied to any specific forge server or service, in particular not tied to Vervis ## Some concepts worth explaining - **Namespaces**: In Vervis there's no such thing as "user/repo". There's no user or group that "owns" a repo. When you create a new repo, you're automatically given admin access to it. Now you're sort of the "owner". But you can give more people access, even admin access, so now there's multiple "owners". In other words, for a given repo, you can have a list of people with access to it, and the role/permissions that each person has. But there's no "owner" concept. In addition, of course, you can extract a list of people who wrote the actual commits in the repo. **Possibly later** there will be some way to group related actors together. I actually just started thinking about it while we were talking. At first I thought maybe have a "Project" concept where we group together related repos/decks/looms/other stuff. But then I thought, what if instead of Project we call it Folder and now we can have Folders inside Folders? Much like in GitLab there's a Group and Subgroup hierarchy, except it's not necessarily tied to roles and permissions. Idk yet. Just initial thoughts. - **Federation of forges**: What if you wanted to see not just local repos on your homeserver, but to browse repos of the whole fediverse? I'm not sure yet how this would work or what the search UI would look like. But keep in mind it's a goal. Another aspect of federation is that users can have access roles in remote repos, and remote actors can have access to your local repos. - **Meaningless URIs**: If you want to install a password manager and you go to codeberg.org/pass/pass and git clone it, how do you know you cloned the right thing, and not some malware pretending to be a password manager? 2 things help you: (1) centralized big forges that you trust to remove spam and malware, otherwise they wouldn't be trusted by the community (2) Unicode chars not allowed in user and repo names, so it's more difficult to make 2 URIs that look the same. So people trust their untrustowrthy eyes... but on the fediverse, when you see some small forge you never heard of, can you trust it doesn't allow unicode chars and actively removes malware? How can you be sure you're cloning the right thing? My solution: Don't type URIs manually, and don't recognize them by eye alone. Reach projects by clicking a link on a website you trust. To help people not trust their eyes alone, URIs don't contain repo names, they contain a random looking identifier. QUESTION: If that password manager has thousands of forks out there, some malicious perhaps, how do I know which one is the "right" one? Without some system to tell me which one if the "official" repo, how do I know? ANSWER: Much like in P2P systems like Scuttlebutt, you use a [petname system](https://spritelyproject.org/news/petname-systems.html). I don't think I'm going to get to that anytime soon, but just FYI, URIs look like https://forge.org/repos/nkj3r2n9f8n29f823 so it's not important to display URIs to people. But it *is* of course useful to let them copy the URI :P even people's profile page URIs look random right now (I'm still considering to change that, idk yet, worried it would allow people to impersonate famous devs and publish malware...) ## Data model This is how stuff works in the *backend*, i.e. the federated forge network. The UI can speak in entirely different terms. 5 primary concepts: - Person: A human interacting with the forge network - Component: A service related to the software development lifecycle, managing some data and/or performing some computation, as part of a software project. Examples for components: A git repo; a ticket tracker; a wiki; a forum. - Project: Named collection of components that are used together in the process of development - Team: A group of people working together towards some shared goal - Role: A named set of allowed operations, that a given person/team can perform on a given component/project (for example "developer", "admin", "translator", "maintainer", etc.) More about people: - People can create teams, projects, components - People can add more people as collaborators (i.e. give access) in projects and components - People can add teams as collaborators More about teams: - Teams can have subteams - Teams can have people members - Teams can have access to projects and components - If a team gets access to some project/component, the team's member people get that access - If a team gets access to some project/components, its subteams get that access as well More about projects: - Projects can contain subprojects - Projects can contain components - People and teams can have access to projects - If a person/team gains access to a project, they usually also can access its components and subprojects More about roles: - Each member of a team has a specific role - When a person/team is given access to a component/project, the level of access is defined by a specific role Notes about what's included in the minimal plain essential feature set: - No teams - No patch trackers, i.e. there are just 2 component types: Repos and Ticket Trackers - Projects don't have subprojects - A person can get to have a role within a project, never directly within a specific component Concepts that may be added in the future: - Organization - Community ## Software develpment services/components Core: - Version control repositories - Patch/MR tracking & code review - Ticket/issue/bug tracking More: - CI - Releases - Package/container registry - UI translation - Wiki - Pages - Snippets/Paste - Workflows i.e. custom ticket fields and transitions Dream/integration: - Forum - Chat - "Governance" tools integration - Vision Mobilization structure for projects - The 5 organizational systems (resources, info, feedback, conflict, decisions) - NVC core commitments as replacement/alternative to CoC? - Community system for mutual support? e.g. in empathic listening, conflict resolution, and even technical things like code review? - Holacracy tools? e.g. for Teams - Audio/video/screen meeting - Realtime shared collaborative coding workspace - Web IDE ## Core feature set Really the most basic plain essentials: - Create projects, and components inside them - Add/remove people as collaborators in projects - See a list of projects to which you have access - Registration, login, password change, password reset - 2 component types: Repos and Ticket Trackers - Repos: - See the name & VCS type of a repo - Ticket trackers: - See tracker's name - See the list of tickets - Open a new ticket - Title (one-line, probably plain-text?) - Description (multi-line markdown) - Close/reopen a ticket - Comment on a ticket - Projects: - See project's name - See project's list of components - See peroject's list of collaborators - Add/remove components - Add/remove collaborators - Manage personal SSH keys: - See list of my keys - Delete a key - Add a new key - Invites: - See a list of invites I've received and haven't replied to - Accept or Reject an invite Pool of the rest: - Create repos, ticket trackers, projects - Create and manage groups of people and people's roles within them - Follow people, repos, projects, specific tickets and MRs - Create and manage tickets - A ticket has an title and a description - People can be assigned to work on a ticket - Tickets can depend on other tickets, even tickets from other decks - Tickets can be closed and reopened - Tickets can have threaded comments - Create and manage MRs - A MR is a specialized kind of Ticket, so it supports all the Ticket features listed above - MRs can depend on tickets, and tickets can depend on MRs (even if they're on unrelated decks/looms) - A MR is a set of 1 of more patches proposed to be applied to a repo - Those patches are provided either as patch diff files, or as a branch to pull commits from - A MR can be updated, by sending a new version - The old versions can still be viewed, at any time - A MR can be merged, or can be closed without being merged - Browse the repos, decks, projects, users, groups on a server - Browse a repo's commit history, and each branch's history - Browse a repo's content at a given commit/branch/tag - Browse a commit/patch, the changes it made to files ## Q&A ### What does it mean for Repos, Decks and Looms to be actors? On the frontend, idk if it means much. But here's the idea: Being an actor means being a standalone object. For example, ticket's aren't actors. They're child objects of Decks. You can't create a standalone Ticket out of nowhere: It must belong under a Deck. And once you create it, it stays under that Deck. It can't be moved around. OTOH, a deck is a standalone object. In Vervis, you can create a new empty Deck at any time. It doesn't need to be under anything. Same for repos. You can always freely spawn them, and move them around. They manage their own access control, so a repo/deck/loom could be moved between folders/projects/people easily. Am I making sense? >In GitLab (and project management apps like Taiga) for example tickets can be moved between issue trackers? - Yeah, the URL changes when it's moved, the issue number also changes too. Yeah, that might be what it is under the hood. - In other words, it's possible then, just that it's represented differently in the backend. - But does the ticket change its URL when it's moved? In a federated situation, it must, because you could be moving it to an issue tracker on a different server. That's more like migration i.e. delete from one tracker and create a copy on another. We could call that move. But as far as the backend can tell, it's delete-and-create-elsewhere. ### What types/examples of activities do Repos record in the outbox? - New commits being pushed - Comment on a ticket - Comment on a MR - Comment on a line of code under a MR (for code review) - New ticket opened - New MR opened - New collaborator added a repo/deck/loom - Collaborator's role changes from X to Y - Person assigned/unassigned to work on a ticket/MR - MR merged / a merge error has occured >"Comment on a MR" - this is a Person commenting on a MR, not a Repo, but it's represented as being under a Repo? - Could be both, a Repo could make an automatic comment, or some CI component could make an automatic comment, e.g. run some tests and comment a report under the MR. So the comment can be by any actor, and can be human-made of machine-made. The comment is hosted by its actor, but it can be displayed along with the whole discussion under a ticket or a MR (same idea as on Mastodon/Fediverse). >When a Person follows another Actor, do they get notifications of all activities or is there a mechanism yet to select what types of activities they get notified about? - You can follow a specific ticket, without following the whole deck. But if you follow a deck, you get all the events, no filtering mechanism yet. For now it's up to the UI to undertand which notifications are important, or just display them all and over time we'll see if it's annoying and learn what sort of filtering is needed. >How to tell which objects can be followed? (so far all Actors can be followed) - (This might be important to convey in the ui, which/how objects can be interacted with) There's no standard way AFAIK, but there's a way to make an educated guess: - If an object has a followers collection, you can definitely follow it - If it's not an actor, you send the Follow activity to the actor that manages the object; there's a hopefully-soon-standard property `managedBy` to identify that actor >Does it also mean a Repo can follow another Repo and trigger some CI on receiving a notification of a certain activity? No mechanism yet to set triggers? Any actor can follow any actor. But automated actors (i.e. all non Person actors, such as repos) follow other actors only when they need it for their functionality. So if it's needed, yes, a repo can follow another repo. CI isn't implemented at all yet, but I imagine CI would be an actor follows (or othersise gets notified) a repo and whenever a commit is pushed or a MR is updated, it runs a CI build and sends back a report using some activity. ### How do people distinguish between repos with the same name on the same instance? The petname system would help with that. But right now, they could distinguish only by URI, and perhaps by the repo content and history being different. And by the identity of people having admin access to the repo. But if 2 repos have access by exactly the same people, and have identical commit history etc. etc. then the URI is the only way. ### How do people distinguish between a repo and its derivatives/forks? When you create a new repo as a fork of an existing one, this info is remembered, so UI can tell you that repo B is a fork of repo A. Obviously it's just a human conveniene thing: You can fork a repo and then force-push whatever you want into the fork, right? Even entirely elete everything and push totally unrelated stuff. But seeing the "was forked from" thing helps, I suppose, much like on the popular forges. >Same thing for mirrored Repos? Can Decks be mirrored, e.g. between instances? There's no mirror functionality in Vervis yet, but I imagine there will be, perhaps even implemented externally by some forge spider tool. A mirrored repo/deck/whatever would be marked as such so you could show that in UI. ### Would not allowing unicode characters in user and repo names be an obstacle for people whose native language is not English? Would this mitigated to some extent by display name fields? In Vervis and in forges in general, there's no reason I see to avoid unicode chars in the display names of users, repos, etc. The unicode issue applies to the *slug*, the name used in URIs. For example a repo with a slug "vervis" but its name could be "Vervis Federated Forge Web App". Since in ForgeFed there's no slug concept, and since URIs paths aren't used to extract any meaning, I suppose it's possible and indeed useful to allow unicode in names of stuff. ### For the MVP, what do you want people to discover on an instance This is an open question, and it depends on how big this MVP is going to be. But priority would be: 1. A list of local repos, decks, looms, sorted by some useful criteria perhaps by name, by latest activity, by creation time, something like that 2. A list of local People, Sorted by name / most recent public event / recent join date 3. Looking at the inbox and outbox of myself, of repos, decks, looms, etc. (i.e. looking at my notifications, looking at my activity, looking at the event stream of a repo/deck/loom...) 4. Looking at tickets 5. Looking at MRs Lower priority: - A list of remote repos/decks/looms/projects knows to my homeserver - Fediverse acivity/event stream (but this is mostly a toy for curious people, I suppose, and Vervis doesn't provide such a thing right now anyway ### What is an activity in Vervis? Any notification of an action done, and any request to do some action, is an Activity. ### What does it mean for a Loom to be tied to a Repo, e.g. does it allow submitting patches by email (the email associated with a Person's account?), but the patch has to purport to originate from the Repo? Looms support submitting a patch/MR (patch and MR are essentially the same thing in Vervis, it's a single unified concept, I can explain more) using API, no email submission currently (pehaps never). But yes, a Loom accepts patches/MRs only for the one Repo it's tied to. A Loom is like the "Pull Requests" tab on Gitea/GitLab/githu8. ### Vision of target audience #### One obvious audience is developers, are there any others? Anyone participating in a project. Even just opening tickets. So, the whole community using the project being developed. I suppose it's the same as most other forges, but I do hope that forge federation will also have a social impact where people feel more empowered to participate. I hope opening an issue or submitting a UI translation would become more accessible. Could be nice for Vervis to look reasonably friendly to non-devs who just open tickets, comment, edit wikis, stuff like that. Perhaps the user can even tell the UI what to focus on (are they a developer who writes code? If not, maybe display a simpler interface?) In other words I don't want to fall into the place where we're devs making a technical tool that only devs understand. Our society depends so much on technology (way more than I wish), let's empower people to participate and not feel powerless (which I'm sure they often do, especially because they're used to that with proprietary software). #### How/where would Vervis fit into the workflow of this theoretical audience? It would be their way to open a ticket, complain about a bug, conveniently do any non-dev action: Translate UI strings, edit documentation, idk what else... without having to see scary words like "Git" or see commit hashes or whatever stuff would be unnecessary and distracting to less technical people. I suppose the UI of opening, manipulating and commenting on issues is the most important in this context, since Vervis doesn't have wiki/docs/translation features right now :P Many projects have guidelines and templates for submitting issues; I'd want it to be easy for people (idk if it's up to Vervis) to understand how to open a ticket and easy to submit it in a reasonably requested format and required info. #### What kinds of use cases is Vervis particularly good at addressing? - Being federated means that interacting with forges doesn't require a new account on every forge - Vervis allows separately creating Repos and Decks, which allows multiple repos to use 1 ticket tracker - Federation also means that self hosting is more appealing than before #### What kinds of use cases is Vervis maybe not as good at supporting right now, but plan to expand on in the future? The current UI is very poor... so Vervis is not-so-good at *most* things right now :P But in the future I hope it will be better at serving both devs and non-devs in easy and convenient collaboration and participation. There are more potential uses cases, such as features related to sysadmins/devops, but I don't expect to get to those features anytime soon... In addition to the core feature set listed above, my priorities for which features to add depend a lot on the ForgeFed spec. For example, I may add CI at some point, to experiment with the federated aspect of it. Oh, one more thing: **Vervis is meant to be a reference implementation of ForgeFed**. To be used by devs of other forges to test their federation code. So Vervis makes a lot of checks on user inputs and tries to produce very specific error messages, to help with debugging. It's important that those errors are conveniently displayed in UI (if the user chooses to see them). ## Q&A: implementation notes ### True or False: in the core features, Repos and Tickets do not exist independently of Projects? ### What is the purpose of ticket tracker names?