ForgeFlux/docs
2
0
Fork 0
Code Issues 1 Pull requests 2 Projects Releases Packages Wiki Activity

Terse content

Browse source 
Reworked the content to be a bit more polished.
This commit is contained in:
dat-adi 2022-01-22 11:11:58 +05:30
parent 747f51c2e3
commit f82ddc5d3e
2 changed files with 23 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
content/_index.md
View file

@ -7,10 +7,8 @@ insert_anchor_links = "right"
It's a Friday evening, and you've sat down to work on some code and halfway through It's a Friday evening, and you've sat down to work on some code and halfway through
testing the code, you realise that there's a problem with a dependency. testing the code, you realise that there's a problem with a dependency.
Something's not supposed to work the way it does, and you hop on to the code-hosting Something's not supposed to work the way it does, and you hop on to the code-hosting
platform, or forge, that you use on a daily basis to search for the library. platform, or forge, that you use on a daily basis to search for the library.
Realizing that the project is not quite hosted on your forge, you close your eyes, Realizing that the project is not quite hosted on your forge, you close your eyes,
before reluctantly heading over to a search engine, to find the project repository before reluctantly heading over to a search engine, to find the project repository
being hosted on another forge that you haven't worked with. being hosted on another forge that you haven't worked with.
@ -19,7 +17,6 @@ At this point, in order to file a bug report, or even send a Pull Request that c
fix the issue, you would be required to create an account on the forge and clone the fix the issue, you would be required to create an account on the forge and clone the
repository and relearn the workings of the particular forge before finally working repository and relearn the workings of the particular forge before finally working
on the code. on the code.
Manually tracking notifications, setting up new remotes for the upstreams, Manually tracking notifications, setting up new remotes for the upstreams,
configuring GPG and SSH keys, and having to set up a new development workflow. configuring GPG and SSH keys, and having to set up a new development workflow.
@ -32,13 +29,11 @@ Worrying about the forge-specific operations that you'll need to perform are a t
the past now. With the inclusion of a bridging feature in your code-hosting platform, the past now. With the inclusion of a bridging feature in your code-hosting platform,
you can finally forget about how other forges behave and whether you'll need to work you can finally forget about how other forges behave and whether you'll need to work
towards creating a new account to contribute. towards creating a new account to contribute.
A contribution, be it a Bug Report, Feature Request, or a Pull Request, now can be A contribution, be it a Bug Report, Feature Request, or a Pull Request, now can be
solved through setting up a bridge to the repository you want to contribute to. solved through setting up a bridge to the repository you want to contribute to.
Days are pleasant and you can continue working on your code after you're done with the Days are pleasant and you can continue working on your code after you're done with the
issue of the library. issue of the library.
You check out and have more time for things that you wanted to work on for the rest of You check out and have more time for things that you wanted to work on for the rest of
the day. the day.
@ -49,7 +44,7 @@ that seeks to get developers to the days of the future!
Implementing bridging leveraging the API space, [Northstar](@/services/northstar.md) Implementing bridging leveraging the API space, [Northstar](@/services/northstar.md)
points, and the [Interface](@/services/interface.md) sets it all up. points, and the [Interface](@/services/interface.md) sets it all up.
Know more about how ForgeFlux works [here!](@/getting-started/how.md) Know more about how ForgeFlux works [here!](@/getting-started/how.md)
We're currently still in active development, and you can check what we've been We're currently still in active development, and you can check what we've been
working on, in the `updates/` section. working on, in the `updates/` section.

76
content/getting-started/how.md
View file

@ -7,69 +7,37 @@ weight = 40
Bridges connect people, and so does ForgeFlux! Bridges connect people, and so does ForgeFlux!
Similar to how bridges are made, with two connecting endpoints for the start point ## Interface
and the end point, ForgeFlux does the same with Interfaces.
[Interfaces](@/services/interface.md) are services that are run on the side of any user, The bridging component in ForgeFlux is called Interface.
and are used as connecting points of the bridge.
These interfaces are responsible for communicating with each other, and interact in the [Interfaces](@/services/interface.md) are programs that run on either
form of messages for a server-server model, and a REST API model for the server-user side of the bridge, i.e, a bridge requires the participation of two
model. interfaces. Currently, Interfaces bridge the following operations:
Interfaces are geared towards performing various operations for the repository,
which include but are not limited to,
- Pull Requests - Pull Requests
- Issues - Issues
- Comments - Comments
- Notifications
- Forking
Recently, ForgeFlux has moved towards implementing the An Interface implementation for a software forge is able to
[ActivityPub protocol](https://activitypub.rocks/) for interoperability with various talk to the forge's API and speak [ActivityPub
Social Networking implementations as well. protocol](https://activitypub.rocks/) for server-to-server
communications. This architecture makes it possible to implement an
Interface for any forge setup.
Implementing the ActivityPub protocol, we've currently established three Actors ## Northstar
in the environment, Repositories, Issues/Pull Requests, and Users.
This way, you can only subscribe to actors and if someone is interested in only a
single issue, they would only be required to interact with that particular Actor rather
than the entire repository.
Deviating from the method that ForgeFed follows, Git is used for changes in the Git Since Interfaces run external to the forges, a method to find Interfaces
repository. that service forges was required.
While [ForgeFed Section 5.2](https://forgefed.peers.community/behavior.html#push-activity) [Northstar](@/services/northstar.md) is a discovery service that maps an
mandates a Push activity to be sent out to all followers whenever there's a `git push`, Interface and the forge that it services. It acts very similar to DNS,
it is not feasible for external implementations like ForgeFlux, which leverage the except instead of querying host names with intent to find corresponding
Forge APIs, to perform this operation since we'll have to consider the API rate limits. IP address, Northstar is queried with the forge's host name to discover
the Interfaces that service it.
Here, we are deviating again from ForgeFed by making it optional. ## Resources
So, federating forges/interfaces will have to periodically do a `git pull` to receive
changes made to the main repository.
For operations such as Issues and Pull Requests, we utilize ActivityPub. -
This is quite similar to [how Mastodon works](https://docs.joinmastodon.org/spec/activitypub/). [ecosystem-architecture](https://github.com/forgeflux-org/spec/blob/master/rfc/1-ecosystem-architecture/1-ecosystem-architecture.md):
describes basic architecture and terminology used in ForgeFlux
However, as the count for interfaces go up in magnitudes, it becomes increasingly hard
to keep track of them.
This is where [Northstar](@/services/northstar.md) comes to play, by implementing a
lookup server that seeks to provide an indexed list of available forge interfaces.
## Has this been done before?
The initial [forgefed](https://forgefed.peers.community/) was an attempt to bridge
this gap, by introducing the concept of bridging the gap between forges.
This approach required for the forge developers to actively participate in the
development of the software.
The present ForgeFlux, focuses on the implementation being present in the API space
instead.
This reduces the interference required on the side of the forges themselves,
and seeks to develop on existing utility and APIs provided.
ForgeFlux, consists of a terminology for the development and utilization of it's
software, which result in terms such as `forges`, and `interfaces` being tossed around.
It is recommended for a reader to go through the [ecosystem-architecture](https://github.com/forgeflux-org/spec/blob/master/rfc/1-ecosystem-architecture/1-ecosystem-architecture.md),
if there is any confusion regarding the usage of particular words in this documentation.