Prepare to publish first draft. ReSpec tooling and sample content (#20)

* Prepare to publish first draft. ReSpec tooling and sample content Signed-off-by: Hadrian Zbarcea <[email protected]> * Update README.md Co-authored-by: Aaron Coburn <[email protected]> * Update spec/index.html Co-authored-by: Pierre-Antoine Champin <[email protected]> * Update spec/index.html Co-authored-by: Pierre-Antoine Champin <[email protected]> * Update spec/index.html Co-authored-by: Pierre-Antoine Champin <[email protected]> * Update spec/index.html Co-authored-by: Pierre-Antoine Champin <[email protected]> * Update spec/index.html Co-authored-by: Pierre-Antoine Champin <[email protected]> * Update spec/index.html Co-authored-by: Pierre-Antoine Champin <[email protected]> * Update spec/user-stories.md Co-authored-by: Pierre-Antoine Champin <[email protected]> * Update spec/glossary.md Co-authored-by: Pierre-Antoine Champin <[email protected]> * Update spec/index.html Co-authored-by: Pierre-Antoine Champin <[email protected]> --------- Signed-off-by: Hadrian Zbarcea <[email protected]> Co-authored-by: Aaron Coburn <[email protected]> Co-authored-by: Pierre-Antoine Champin <[email protected]>
w3c · Dec 11, 2024 · 3141428 · 3141428
1 parent dc8bf16
commit 3141428
Show file tree

Hide file tree

Showing 6 changed files with 164 additions and 38 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+/index.html
diff --git a/README.md b/README.md
@@ -3,3 +3,45 @@
 
 This is the repository for lws-ucs. You're welcome to contribute! Let's make the Web rock our socks
 off!
+
+## Defining User Stories
+
+LWS user stories are classified under the following categories:
+
+* Functional: specific features or capabilities (e.g., "As a user, I want to reset my password so that I can regain access to my account.").
+* Non-Functional: related to qualities of service, such as performance, security, or scalability (e.g., "As an administrator, I want the storage server to handle up to 10,000 concurrent connections at peak.").
+* Technical: related to infrastructure tasks (e.g., "As a Service Provider, I want the ability to archive LWS storages").
+* Spike: used to explore or research an unknown aspect of the project (e.g., "Research what Identity System supports delegation.").
+
+## How to build this spec
+
+This repository uses the [ReSpec toolchain](https://respec.org/docs/). Please find below a quick getting started cheatsheet using the [command line](https://respec.org/docs/#using-command-line) tools.
+
+Setup `respec` for multiple use:
+```
+$ npm install --global respec
+```
+Update your environment with the following variables:
+```
+export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1
+export PUPPETEER_EXECUTABLE_PATH="/usr/bin/google-chrome"
+# replace "/usr/bin/google-chrome" with path to Chrome executable on your system.
+# On MacOS, it's generally:
+# "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+```
+This spec uses the `data-include` attribute. For `respec` to work locally, the content MUST be served by a web server. One easy way to achive that is to run one from the project directory:
+```
+# Install a local HTTP server if not already installed (one time)
+$ npm install -g http-server
+
+# Start the server in your project directory
+$ http-server
+Starting up http-server, serving ./
+
+http-server version: 14.1.1
+```
+
+Note that the server starts on port 8080. Now you can run `respec` to generate the spec [`index.html`](http://localhost:8080/index.html) in the project root and test changes.
+```
+$ respec --src http://localhost:8080/spec/index.html --out index.html
+```
diff --git a/index.html b/index.html
diff --git a/spec/glossary.md b/spec/glossary.md
@@ -0,0 +1,2 @@
+ - <dfn>Storage Provider</dfn> - A Service Provider that ofers a cloud-based data storage service conformant with the LWS protocol.
+ - <dfn>Identity Provider</dfn> - The party that manages the subscriber’s primary authentication credentials and issues assertions derived from those credentials ; see [NIST definition](https://csrc.nist.gov/glossary/term/identity_provider)
diff --git a/spec/index.html b/spec/index.html
@@ -0,0 +1,66 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <title>Spec proposal</title>
+    <script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
+    <script class='remove'>
+      // See https://github.com/w3c/respec/wiki/ for how to configure ReSpec
+      var respecConfig = {
+        specStatus: "ED",
+        shortName: "lws-ucs",
+        copyrightStart:  "2024",
+        // previousPublishDate:  "N/A",
+        editors: [
+          { name: "Pierre-Antoine Champin" },
+          { name: "Hadrian Zbarcea" },
+        ],
+        group: "wg/lws",
+        wg: "Linked Web Storage",
+        maxTocLevel: 3,
+        localBiblio: {
+          RESUMABLE_UPLOADS: {
+            title: "Resumable Uploads for HTTP",
+            authors: ["M. Kleidl", "G. Zhang", "L. Pardue"],
+            date: "3 December 2024",
+            href: "https://httpwg.org/http-extensions/draft-ietf-httpbis-resumable-upload",
+            status: "Draft",
+            publisher: "IETF",
+          }
+        },
+        lint: {
+          "no-unused-dfns": false,
+        },
+      };
+    </script>
+  </head>
+  <body>
+    <section id="abstract">
+      <p>
+        User stories and use cases for the LWS spec.
+      </p>
+    </section>
+    <section id="sotd">
+    </section>
+
+    <section id="introduction">
+      <h2>Introduction</h2>
+      <p>
+        See <a href="https://github.com/w3c/respec/wiki/User's-Guide">ReSpec's user guide</a>
+        for how toget started!
+      </p>
+    </section>
+
+    <section id="use-cases">
+      <h2>Use Cases</h2>
+      <p>The use cases for this specification are documented below.</p>
+      <div data-include="user-stories.md" data-include-format="markdown" data-include-replace="true"></div>
+    </section>
+    <section id="glossary">
+      <h2>Glossary</h2>
+      <p>The glossary provides definitions of key terms and concepts used throughout this specification. It serves as a quick reference to ensure clarity and a shared understanding among readers and contributors. By standardizing terminology, the glossary supports consistent communication and alignment in interpreting this specification.</p>
+      <div data-include="glossary.md" data-include-format="markdown" data-include-replace="true"></div>
+    </section>
+
+  </body>
+</html>
diff --git a/spec/user-stories.md b/spec/user-stories.md
@@ -0,0 +1,53 @@
+## Functional Stories
+
+### Use Case 1: Large HTTP uploads
+
+As a `user` and/or a `software developer`,
+I want to upload large files that may or may/not complete due to network and/or server issues.  Further, for very large uploads also knowing what percentage of a file(s) that is uploaded is handy to have as both user and developer.
+
+#### Preconditions:
+
+User/developer is working with large files.
+
+#### Trigger:
+
+User attempts to upload a file.
+
+#### Actors:
+
+ - User with a large file
+ - the server to which the file needs to be uploaded to
+
+#### Distinction:
+
+N/A
+
+#### Scenario:
+
+Large file(s) is correctly uploaded and user knows how long it was going to take within a reasonably degree of accuracy.
+
+#### Alternative case(s):
+
+If large file handling is not available user/developer can get notification to the lack of this particular service or an alternate unspecified method for these sizes of files.
+
+#### Error scenario:
+
+ - network crash and/or interruption
+ - server crash and/or interruption
+ - any interference that would disrupt the transfer of the large file(s) (ie cat on keyboard)
+
+#### Acceptance Criteria:
+
+User/developer has at least one methodology that will be available in order to upload (or resume) a large file(s) upload.
+
+#### References:
+
+- [[[RESUMABLE_UPLOADS]]]
+
+
+## Non-Functional Stories
+
+## Technical Stories
+
+## Spike Stories
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		- <dfn>Storage Provider</dfn> - A Service Provider that ofers a cloud-based data storage service conformant with the LWS protocol.
		- <dfn>Identity Provider</dfn> - The party that manages the subscriber’s primary authentication credentials and issues assertions derived from those credentials ; see [NIST definition](https://csrc.nist.gov/glossary/term/identity_provider)