Commit

Author:

Hash:

Timestamp:

+54 -22 +/-1 browse

Kevin Schoon [me@kevinschoon.com]

401d1b179845656950b02cef65819bfdc48f10bb

Fri, 06 Jun 2025 13:50:28 +0000 (4 months ago)

a few updates
1diff --git a/README.md b/README.md
2index 22ac7f1..cd3da6e 100644
3--- a/README.md
4+++ b/README.md
5 @@ -1,20 +1,29 @@
6 # ForgeFeed
7
8- ForgeFeed is a small collection of standards which when implemented allow your
9- [forge](https://en.wikipedia.org/wiki/Forge_(software)) to better federate with
10- others across the internet.
11-
12 *NOTE: This specification is a W.I.P and should not yet be implemented
13 anywhere.*
14
15+ ForgeFeed is a collection of specifications and recommendations which when
16+ implemented can enhance interoperability and content discovery of different
17+ [code forges](https://en.wikipedia.org/wiki/Forge_(software))
18+ across the internet.
19+
20+ Below we cover the following specifications:
21+
22+ Repository URI - URI Identifier for WebFinger Queries
23+ WebFinger Query - Metadata Queries via WebFinger
24+ RSS Specification - Repository Discovery via RSS
25+
26+
27 ## Repository URI
28
29- A repository URI provides a unique identifier for referencing a repository
30- that is present in a given code forge. This value is similar to
31- [RFC7565](https://datatracker.ietf.org/doc/html/rfc7565). The slug and
32- hostname part MUST match the URI path specification as defined in
33+ A repository URI identifies a code repository and optionally the host that is
34+ resides on. This value is similar to
35+ [RFC7565](https://datatracker.ietf.org/doc/html/rfc7565). The slug and hostname
36+ part MUST match the URI path specification as defined in
37 [RFC3986-3.3](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) while the
38- hostname, if specified, must match [RFC3986-3.2.2](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2)
39+ hostname, if specified, must match
40+ [RFC3986-3.2.2](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2)
41
42 repository-uri = prefix slug hostname
43
44 @@ -87,6 +96,13 @@ an example response about a fictitious repository:
45 }
46 },
47 {
48+ "rel": "http://feed-forge.org/rel/clone",
49+ "href": "https://example.org/example/spartacus",
50+ "properties": {
51+ "http://feed-forge.org/ns/vcs-type": "git"
52+ }
53+ },
54+ {
55 "rel": "http://forge-feed.org/rel/license",
56 "href": "https://example.com/example/spartacus/tree/LICENSE",
57 "properties": {
58 @@ -195,6 +211,21 @@ A license SPDX identifier and link to the license's full text.
59 }
60 ```
61
62+ ### Clone Links
63+
64+ Clone links define how one can download a copy of the remote
65+ software onto their own server.
66+
67+ ```json
68+ {
69+ "rel": "http://feed-forge.org/rel/clone",
70+ "href": "https://example.org/example/spartacus",
71+ "properties": {
72+ "http://feed-forge.org/ns/vcs-type": "git"
73+ }
74+ }
75+ ```
76+
77 #### Chat Links
78
79 Links to chatrooms: IRC, Matrix, XMPP, etc.
80 @@ -271,7 +302,7 @@ request.
81 404
82 GET https://example.org/.well-known/webfinger?resource=repository:example/non-existent-repository
83 404
84-
85+
86 # RSS Feeds
87
88 Your forge needs to expose an RSS feed in order for other peers to determine
89 @@ -295,7 +326,8 @@ element such as below at the root domain of your forge. For example,
90 type="application/rss+xml"
91 title="Recent Forge Activity"
92 href="https://code.example.org/firehose.xml" />
93- <meta name="forge-feed:index" content="https://code.example.org/firehose.xml"/>
94+ <!-- index-url refers to the RSS link on the current webpage which contains forge updates -->
95+ <meta name="forge-feed:index-url" content="https://code.example.org/firehose.xml"/>
96 </head>
97 <body>
98 ...
99 @@ -326,22 +358,22 @@ below).
100 <lastBuildDate>Tue, 03 Jun 2025 14:18:48 +0000</lastBuildDate>
101 <ttl>60</ttl>
102 <item>
103- <title>Spartacus</title>
104- <description>A Text Adventure Written in FORTRAN 77<description/>
105- <author>admin@example.org (Administrator)</author>
106+ <title>Spartacus</title>
107+ <description>A Text Adventure Written in FORTRAN 77<description/>
108+ <author>admin@example.org (Administrator)</author>
109 <!-- Link to an HTTP representation of the repository -->
110- <link>https://example.org/example/spartacus</link>
111+ <link>https://example.org/example/spartacus</link>
112 <!-- Guid may be the repository name at a particular commit id-->
113- <guid>https://example.org/example/spartacus@f28ce68f16e338355e55372bc788e8ea5feda470</guid>
114- <pubDate>Sun, 25 May 2025 18:23:03 +0200</pubDate>
115+ <guid>https://example.org/example/spartacus@f28ce68f16e338355e55372bc788e8ea5feda470</guid>
116+ <pubDate>Sun, 25 May 2025 18:23:03 +0200</pubDate>
117 <!-- Optional enclosure with an image reference if your forge supports this -->
118 <enclosure url="https://example.org/example/spartacus/raw/main/logo.png" length="12216320" type="image/png" />
119 <!-- Although highly recommended, the fields below are optional -->
120- <repository>
121+ <repository>
122 <!-- repository URI described above -->
123- <webfinger>repository:example/spartacus</webfinger>
124- </repository>
125- </item>
126+ <webfinger>repository:example/spartacus</webfinger>
127+ </repository>
128+ </item>
129 </channel>
130 </rss>
131 ```
132 @@ -355,7 +387,7 @@ about code repositories hosted on your server.
133
134 ```xml
135 <repository>
136- <webfinger>repository:example/spartacus@example.org</webfinger>
137+ <webfinger>repository:example/spartacus@example.org</webfinger>
138 </repository>
139 ```
140