docs: editorial fixes to ipips

ipfs · Mar 30, 2023 · 8d24f99 · 8d24f99
1 parent 7f8d83d
commit 8d24f99
Show file tree

Hide file tree

Showing 18 changed files with 201 additions and 203 deletions.
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -5,9 +5,11 @@
 
 # global IPIP
 IPIP/ @ipfs/specs-stewards
+src/ipips/ @ipfs/specs-stewards
 
 # Selected Spec Stewards can be defined below to be automatically requested for
 # review when someone opens a pull request that modifies area of their
 # interest.
 
-http-gateways/  @lidel
+http-gateways/  @lidel
+src/http-gateways/ @lidel
diff --git a/ipip-template.md b/ipip-template.md
@@ -1,10 +1,14 @@
-# IPIP-0: InterPlanetary Improvement Proposal Template
+---
+# IPIP number should  match its pull request number. After you open a PR,
+# please update title and update the filename to `ipip0000`.
+date: YYYY-MM-DD
+editors:
+  - name: Your Name
+---
 
-<!-- IPIP number should  match its pull request number. After you open a PR,
-please update title and include anqabbreviated title in the filename too:
-`0000-draft-title-abbrev.md`. -->
+# IPIP-0000: InterPlanetary Improvement Proposal Template
 
-- Start Date: YYYY-MM-DD
+<!-- TODO: MAKE THIS FRONTMATTER FIELD -->
 - Related Issues:
   - (add links here)
 

diff --git a/src/_includes/specs/http-gateways/http.html b/src/_includes/specs/http-gateways/http.html
@@ -0,0 +1,14 @@
+<dl>
+  <dt><a href="/http-gateways/path-gateway/">Path Gateways</a></dt>
+  <dd>
+    The most versatile form of IPFS Gateway is a Path Gateway. It exposes namespaces like <code>/ipfs/</code> and
+    <code>/ipns/</code> under an HTTP server root and provides basic primitives for integrating IPFS resources
+    within the existing HTTP stack.
+  </dd>
+  <dt><a href="/http-gateways/trustless-gateway/">Trustless Gateways</a></dt>
+  <dd>
+    Trustless Gateways are a minimal <em>subset</em> of <a href="/http-gateways/path-gateway/">Path Gateways</a>
+    that allow light IPFS clients to retrieve data behind a CID and verify its integrity without delegating any
+    trust to the gateway itself.
+  </dd>
+</dl>
diff --git a/src/_includes/specs/http-gateways/web.html b/src/_includes/specs/http-gateways/web.html
@@ -0,0 +1,19 @@
+<dl>
+  <dt><a href="/http-gateways/dnslink-gateway/">DNSLink Gateways</a></dt>
+  <dd>
+    DNSLink Gateways are an extension of <a href="/http-gateways/path-gateway/">Path Gateways</a> that enable hosting a
+    specific content path under a specific DNS name.
+  </dd>
+  <dt><a href="/http-gateways/subdomain-gateway/">Subdomain Gateways</a></dt>
+  <dd>
+    Subdomain Gateways are an extension of <a href="/http-gateways/path-gateway/">Path Gateways</a> that
+    enable website hosting isolated per CID/name, while remaining compatible with web browsers relative pathing and
+    the security model of the web.
+  </dd>
+  <dt><a href="/http-gateways/web-redirects-file/">Redirects File</a></dt>
+  <dd>
+    The Redirects File specification is an extension of the Subdomain Gateway and DNSLink Gateway specifications that
+    enables URL redirects or rewrites by adding redirect rules to a0 file stored underneath the root CID of a web
+    site.
+  </dd>
+</dl>
diff --git a/src/_includes/specs/ipips.html b/src/_includes/specs/ipips.html
@@ -0,0 +1,7 @@
+<dl>
+  <dt><a href="/ipips/ipip-0001/">IPIP-0001: Lightweight Improvement Process for IPFS Specifications</a></dt>
+  <dt><a href="/ipips/ipip-0002/">IPIP-0002: _redirects File Support on Web Gateways</a></dt>
+  <dt><a href="/ipips/ipip-0288/">IPIP-0288: TAR Response Format on HTTP Gateways</a></dt>
+  <dt><a href="/ipips/ipip-0328/">IPIP-0328: JSON and CBOR Response Formats on HTTP Gateways</a></dt>
+  <dt><a href="/ipips/ipip-0337/">IPIP-0337: Delegated Content Routing HTTP API</a></dt>
+</dl>
diff --git a/src/_includes/specs/ipns.html b/src/_includes/specs/ipns.html
@@ -0,0 +1,11 @@
+<dl>
+  <dt><a href="/ipns/ipns-record/">IPNS Record and Protocol</a></dt>
+  <dd>
+    Specifies the IPNS protocol in a language-agnostic manner, allowing everyone to create a compatible IPNS Record Publisher
+    or Resolver.
+  </dd>
+  <dt><a href="/ipns/ipns-pubsub-router/">IPNS PubSub Router</a></dt>
+  <dd>
+    Specifies how to publish and retrieve IPNS records using libp2p PubSub router.
+  </dd>
+</dl>
diff --git a/src/_includes/specs/meta.html b/src/_includes/specs/meta.html
@@ -0,0 +1,15 @@
+<dl>
+  <dt><a href="/meta/code-of-conduct/">Code of Conduct</a></dt>
+  <dd>
+    The code of conduct that all community participants are held to.
+  </dd>
+  <dt><a href="/meta/ipip-process/">IPIP Process</a></dt>
+  <dd>
+    The specification documenting the process throuh which a new IPIP should be proposed.
+  </dd>
+  <dt><a href="/meta/spec-for-specs/">Spec for Specs</a></dt>
+  <dd>
+    Specifies the format and system used to create and maintain specifications for
+    the interplanetary stack.
+  </dd>
+</dl>
diff --git a/src/http-gateways/index.html b/src/http-gateways/index.html
@@ -12,44 +12,13 @@ <h3>HTTP</h3>
   <p>
     Low-level gateways that expose IPFS resources over HTTP protocol.
   </p>
-  <dl>
-    <dt><a href="/http-gateways/path-gateway/">Path Gateways</a></dt>
-    <dd>
-      The most versatile form of IPFS Gateway is a Path Gateway. It exposes namespaces like <code>/ipfs/</code> and
-      <code>/ipns/</code> under an HTTP server root and provides basic primitives for integrating IPFS resources
-      within the existing HTTP stack.
-    </dd>
-    <dt><a href="/http-gateways/trustless-gateway/">Trustless Gateways</a></dt>
-    <dd>
-      Trustless Gateways are a minimal <em>subset</em> of <a href="/http-gateways/path-gateway/">Path Gateways</a>
-      that allow light IPFS clients to retrieve data behind a CID and verify its integrity without delegating any
-      trust to the gateway itself.
-    </dd>
-  </dl>
+  {% include 'specs/http-gateways/http.html' %}
   <h3>Web</h3>
   <p>
     Designed for website hosting and improved interoperability with web browsers and
     <a href="https://en.wikipedia.org/wiki/Same-origin_policy">origin-based security model</a>.
   </p>
-  <dl>
-    <dt><a href="/http-gateways/dnslink-gateway/">DNSLink Gateways</a></dt>
-    <dd>
-      DNSLink Gateways are an extension of <a href="/http-gateways/path-gateway/">Path Gateways</a> that enable hosting a
-      specific content path under a specific DNS name.
-    </dd>
-    <dt><a href="/http-gateways/subdomain-gateway/">Subdomain Gateways</a></dt>
-    <dd>
-      Subdomain Gateways are an extension of <a href="/http-gateways/path-gateway/">Path Gateways</a> that
-      enable website hosting isolated per CID/name, while remaining compatible with web browsers relative pathing and
-      the security model of the web.
-    </dd>
-    <dt><a href="/http-gateways/web-redirects-file/">Redirects File</a></dt>
-    <dd>
-      The Redirects File specification is an extension of the Subdomain Gateway and DNSLink Gateway specifications that
-      enables URL redirects or rewrites by adding redirect rules to a0 file stored underneath the root CID of a web
-      site.
-    </dd>
-  </dl>
+  {% include 'specs/http-gateways/web.html' %}
 </main>
 
 {% include 'footer.html' %}
diff --git a/src/index.html b/src/index.html
@@ -20,43 +20,6 @@ <h2 class="pitch-title">Specifying IPFS and the Interplanetary stack.</h2>
   <p class="pitch-subtitle">
     The technology that powers the content-addressable web is being standardized here.
   </p>
-  <!--
-  <div class="basic-grid">
-    <div class="pitch">
-      <h3>High-quality open standards</h3>
-      <p>
-        We aim to fully define implementation behaviour and to empower anyone to build their
-        own system that fits into the interplanetary ecosystem without needing to reverse-engineer
-        the behavior of other implementations.
-      </p>
-    </div>
-    <div class="pitch">
-      <h3>Comprehensive test suites</h3>
-      <p>
-        A specification is only as useful as it is both testable and tested. We are building extensive
-        test suites that allow specifications to prove their interoperability and implementations to demonstrate
-        their correctness.
-        </p>
-    </div>
-    <div class="pitch">
-      <h3>Testing infrastructure</h3>
-      <p>
-        We build tools to support detecting interoperability issues early and often as part of CI/CD pipelines
-        and to report on implementation maturity as the stack evolves so that people who build on top of the
-        interplanetary stack can know what they can use in production.
-      </p>
-    </div>
-    <div class="pitch">
-      <h3>An open governance model</h3>
-      <p>
-        We guarantee community ownership of the standards, of the standards-production process, and of
-        the infrastructure to operate it, in collective pursuit of efficient, transformative, ethical
-        technology.
-      </p>
-    </div>
-  </div>
-  -->
-
   <section>
     <h2>Specifications</h2>
     <p>
@@ -69,56 +32,24 @@ <h3><a href="/http-gateways/">HTTP Gateways</a></h3>
           IPFS Gateway acts as a bridge between traditional HTTP clients and IPFS. Through the gateway, users can download files,
           directories and other IPLD data stored in IPFS as if they were stored in a traditional web server.
         </p>
-        <dl>
-          <dt><a href="/http-gateways/path-gateway/">Path Gateways</a></dt>
-          <dd>
-            The most versatile form of IPFS Gateway is a Path Gateway. It exposes namespaces like <code>/ipfs/</code> and
-            <code>/ipns/</code> under an HTTP server root and provides basic primitives for integrating IPFS resources
-            within the existing HTTP stack.
-          </dd>
-          <dt><a href="/http-gateways/trustless-gateway/">Trustless Gateways</a></dt>
-          <dd>
-            Trustless Gateways are a minimal <em>subset</em> of <a href="/http-gateways/path-gateway/">Path Gateways</a>
-            that allow light IPFS clients to retrieve data behind a CID and verify its integrity without delegating any
-            trust to the gateway itself.
-          </dd>
-          <dt><a href="/http-gateways/dnslink-gateway/">DNSLink Gateways</a></dt>
-          <dd>
-            DNSLink Gateways are an extension of <a href="/http-gateways/path-gateway/">Path Gateways</a> that enable hosting a
-            specific content path under a specific DNS name.
-          </dd>
-          <dt><a href="/http-gateways/subdomain-gateway/">Subdomain Gateways</a></dt>
-          <dd>
-            Subdomain Gateways are an extension of <a href="/http-gateways/path-gateway/">Path Gateways</a> that
-            enable website hosting isolated per CID/name, while remaining compatible with web browsers relative pathing and
-            the security model of the web.
-          </dd>
-          <dt><a href="/http-gateways/web-redirects-file/">Redirects File</a></dt>
-          <dd>
-            The Redirects File specification is an extension of the Subdomain Gateway and DNSLink Gateway specifications that
-            enables URL redirects or rewrites by adding redirect rules to a0 file stored underneath the root CID of a web
-            site.
-          </dd>
-        </dl>
+        {% include 'specs/http-gateways/http.html' %}
+        {% include 'specs/http-gateways/web.html' %}
       </section>
       <section>
         <h3><a href="/ipns/">InterPlanetary Naming System</a></h3>
         <p>
           The InterPlanetary Naming System (IPNS) is a naming system responsible for creating, reading and updating mutable pointers to data.
         </p>
-
-        <dl>
-          <dt><a href="/ipns/ipns-record/">IPNS Record and Protocol</a></dt>
-          <dd>
-            Specifies the IPNS protocol in a language-agnostic manner, allowing everyone to create a compatible IPNS Record Publisher
-            or Resolver.
-          </dd>
-          <dt><a href="/ipns/ipns-pubsub-router/">IPNS PubSub Router</a></dt>
-          <dd>
-            Specifies how to publish and retrieve IPNS records using libp2p PubSub router.
-          </dd>
-        </dl>
-
+        {% include 'specs/ipns.html' %}
+      </section>
+      <section>
+        <h3><a href="/ipips/">InterPlanetary Improvement Proposals</a></h3>
+        <p>
+          InterPlanetary Improvement Proposals (IPIP) are an orderly mechanism to consider
+          changes to the IPFS specification. They are not changes to the specification itself,
+          but their approval leads to a change in the specification.
+        </p>
+        {% include 'specs/ipips.html' %}
       </section>
       <section>
         <h3><a href="/meta/">Meta</a></h3>
@@ -127,27 +58,7 @@ <h3><a href="/meta/">Meta</a></h3>
           project work: what the core values are, what the governance model is, how to produce documents,
           etc.
         </p>
-        <dl>
-          <dt><a href="/meta/code-of-conduct/">Code of Conduct</a></dt>
-          <dd>
-            The code of conduct that all community participants are held to.
-          </dd>
-          <dt><a href="/meta/spec-for-specs/">Spec for Specs</a></dt>
-          <dd>
-            Specifies the format and system used to create and maintain specifications for
-            the interplanetary stack.
-          </dd>
-          <!-- <dt><a href="/meta/license/">Document License</a></dt>
-          <dt>Document License</dt>
-          <dd>
-            tk
-              WHATWG:
-              Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License. To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.
-              W3C:
-              Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
-          </dd>
-              -->
-        </dl>
+        {% include 'specs/meta.html' %}
       </section>
     </div>
   </section>

diff --git a/src/ipips/index.html b/src/ipips/index.html
@@ -0,0 +1,15 @@
+---
+title: InterPlanetary Improvement Proposals
+description: |
+  An InterPlanetary Improvement Proposals (IPIP) provides an orderly mechanism for
+  considering proposed changes to IPFS specifications. An IPIP proposal is not to be the spec itself;
+  the approval of an IPIP leads to an update to a specification.
+---
+
+{% include 'header.html' %}
+
+<main>
+  {% include 'specs/ipips.html' %}
+</main>
+
+{% include 'footer.html' %}
diff --git a/src/ipips/ipip-0001.md b/src/ipips/ipip-0001.md
@@ -1,11 +1,18 @@
-# IPIP 0001: Lightweight Improvement Process for IPFS Specifications
-
-- Start Date: 2022-06-10
+---
+date: 2022-06-10
+editors:
+  - name: Marcin Rataj
+    github: lidel
+  - name: wilkyr31d
+    github: wilkyr31d
+---
+
+# IPIP-0001: Lightweight Improvement Process for IPFS Specifications
+
+<!-- TODO: MAKE THIS FRONTMATTER FIELD -->
 - Related Issues:
   - [ipfs/specs/issues/286](https://github.com/ipfs/specs/issues/286)
 
-## Summary
-
 This _InterPlanetary Improvement Proposal_ (IPIP) introduces a lightweight
 "request for comments/change" process for the IPFS specifications
 [repository][1].
@@ -45,7 +52,7 @@ To illustrate:
 
 ### IPIP Lifecycle
 
-Up-to-date process and IPIP lifecycle will be published in [`ipfs/specs/IPIP_PROCESS.md`](../IPIP_PROCESS.md).
+Up-to-date process and IPIP lifecycle will be published in :cite[ipip-process].
 
 <details>
   <summary>Click to expand the initial (historical) flow</summary>
@@ -56,10 +63,10 @@ Changes to IPFS specifications can be proposed by opening a Git pull-request
 (PR) against the `ipfs/specs` repository.
 
 In addition to specification changes, such PR must include a short **IPIP
-document** based on the template in [`ipfs/specs/IPIP/0000-template.md`](./0000-template.md).
+document** based on the template in [`ipfs/specs/ipip-template.md`](https://github.com/ipfs/specs/blob/main/ipip-template.md).
 
 When a new specification file is added to the repo, it should be based on
-the template at [`ipfs/specs/template.md`](../template.md).
+the template at [`ipfs/specs/template.md`](https://github.com/ipfs/specs/blob/main/template.md).
 
 ### Reviewing IPIPs
 

diff --git a/src/ipips/ipip-0002.md b/src/ipips/ipip-0002.md
@@ -1,13 +1,23 @@
-# IPIP 0002: _redirects File Support on Web Gateways
-
-- Start Date: 2022-06-15
+---
+date: 2022-06-15
+editors:
+  - name: Justin Johnson
+    github: justincjohnson
+  - name: Marcin Rataj
+    github: lidel
+  - name: Henrique Dias
+    github: hacdias
+    url: https://hacdias.com/
+---
+
+# IPIP-0002: _redirects File Support on Web Gateways
+
+<!-- TODO: MAKE THIS FRONTMATTER FIELD -->
 - Related Issues:
   - [ipfs/specs/issues/257](https://github.com/ipfs/specs/issues/257)
   - [ipfs/kubo/pull/8890](https://github.com/ipfs/kubo/pull/8890)
   - [ipfs-docs/pull/1275](https://github.com/ipfs/ipfs-docs/pull/1275)
 
-## Summary
-
 Provide support for URL redirects and rewrites for web sites hosted on Subdomain or DNSLink Gateways, thus enabling support for [single-page applications (SPAs)](https://en.wikipedia.org/wiki/Single-page_application), and avoiding  [link rot](https://en.wikipedia.org/wiki/Link_rot) when moving to IPFS-backed hosting.
 
 ## Motivation
@@ -36,7 +46,7 @@ For performance reasons this proposal does not include forced redirect support (
 
 If a `_redirects` file exists but is unable to be processed, perhaps not even parsing correctly, errors will be returned to the user viewing the site via the Gateway.
 
-The detailed specification is added in [`http-gateways/REDIRECTS_FILE.md`](../http-gateways/REDIRECTS_FILE.md).
+The detailed specification is added in :cite[web-redirects-file].
 
 ### Test fixtures