Initial commit

privacycg · Apr 21, 2020 · 3221bae · 3221bae
commit 3221bae
Show file tree

Hide file tree

Showing 4 changed files with 263 additions and 0 deletions.
diff --git a/Makefile b/Makefile
@@ -0,0 +1,45 @@
+# Makefile --- A simple Makefile for working on specs.
+
+# This is a generic Makefile for generating HTML documents from Bikeshed
+# and Markdown source files.
+
+# Bikeshed (.bs) is a popular format for writing specifications in. This
+# Makefile assumes you have a local install of bikeshed. Installation
+# instructions can be found here:
+#
+#     https://tabatkins.github.io/bikeshed/#installing
+
+# Markdown (.md) is commonly used for README files, explainers, and
+# other documentation adjacent to specifications.
+#
+# This Makefile assumes you have a local install of the Python markdown2
+# module. You can install it like any other Python module, with pip:
+#
+#     pip install markdown2
+#
+# It also assumes you have doctoc installed. This is a tool that
+# automatically generates Table of Contents for Markdown files. It can
+# be installed like any other NPM module:
+#
+#    npm install -g doctoc
+
+docs    = $(patsubst %.md,%.html,$(wildcard *.md))
+specs   = $(patsubst %.bs,%.html,$(wildcard *.bs))
+
+.PHONY: all docs specs clean
+.SUFFIXES: .bs .md .html
+
+all: docs specs
+docs: $(docs)
+specs: $(specs)
+
+clean:
+	rm -f $(docs) $(specs) *~
+
+.bs.html:
+	bikeshed spec $< $@
+
+.md.html:
+	echo "<!doctype html>\n<meta charset=utf-8>\n" > $@
+	doctoc $<
+	markdown2 $< >> $@
diff --git a/README.md b/README.md
@@ -0,0 +1,171 @@
+# Example Privacy CG explainer and spec source files
+
+This repository contains explainer and spec templates that can be used
+by folks working on proposals and work items in the Privacy CG.
+
+This file is the sample explainer, which begins after this section. The
+sample explainer text itself comes from the
+[TAG](https://w3ctag.github.io/)'s excellent
+[explainer explainer](https://w3ctag.github.io/explainers).
+
+There is also **[sample work item spec source](work-item.bs)** (in
+Bikeshed), and a [Makefile](Makefile) that can be used for testing
+explainer and spec changes locally. Don't forget to rename
+`work-item.bs` to `shortname.bs`!
+
+<!-- When creating a new explainer, delete everything above the following line -->
+# [Title]
+
+[Keep one of these sentences:]
+
+A [Proposal](https://privacycg.github.io/charter.html#proposals)
+of the [Privacy Community Group](https://privacycg.github.io/).
+
+A [Work Item](https://privacycg.github.io/charter.html#work-items)
+of the [Privacy Community Group](https://privacycg.github.io/).
+
+## Authors:
+
+- [Author 1]
+- [Author 2]
+- [etc.]
+
+## Participate
+- https://github.com/privacycg/deliverable/issues
+
+## Table of Contents [if the explainer is longer than one printed page]
+
+[You can generate a Table of Contents for markdown documents using a tool like [doctoc](https://github.com/thlorenz/doctoc).]
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Introduction](#introduction)
+- [Goals [or Motivating Use Cases, or Scenarios]](#goals-or-motivating-use-cases-or-scenarios)
+- [Non-goals](#non-goals)
+- [[API 1]](#api-1)
+- [[API 2]](#api-2)
+- [Key scenarios](#key-scenarios)
+  - [Scenario 1](#scenario-1)
+  - [Scenario 2](#scenario-2)
+- [Detailed design discussion](#detailed-design-discussion)
+  - [[Tricky design choice #1]](#tricky-design-choice-1)
+  - [[Tricky design choice 2]](#tricky-design-choice-2)
+- [Considered alternatives](#considered-alternatives)
+  - [[Alternative 1]](#alternative-1)
+  - [[Alternative 2]](#alternative-2)
+- [Stakeholder Feedback / Opposition](#stakeholder-feedback--opposition)
+- [References & acknowledgements](#references--acknowledgements)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Introduction
+
+[The "executive summary" or "abstract".
+Explain in a few sentences what the goals of the project are,
+and a brief overview of how the solution works.
+This should be no more than 1-2 paragraphs.]
+
+## Goals [or Motivating Use Cases, or Scenarios]
+
+[What is the **end-user need** which this project aims to address?]
+
+## Non-goals
+
+[If there are "adjacent" goals which may appear to be in scope but aren't,
+enumerate them here. This section may be fleshed out as your design progresses and you encounter necessary technical and other trade-offs.]
+
+## [API 1]
+
+[For each related element of the proposed solution - be it an additional JS method, a new object, a new element, a new concept etc., create a section which briefly describes it.]
+
+```js
+// Provide example code - not IDL - demonstrating the design of the feature.
+
+// If this API can be used on its own to address a user need,
+// link it back to one of the scenarios in the goals section.
+
+// If you need to show how to get the feature set up
+// (initialized, or using permissions, etc.), include that too.
+```
+
+[Where necessary, provide links to longer explanations of the relevant pre-existing concepts and API.
+If there is no suitable external documentation, you might like to provide supplementary information as an appendix in this document, and provide an internal link where appropriate.]
+
+[If this is already specced, link to the relevant section of the spec.]
+
+[If spec work is in progress, link to the PR or draft of the spec.]
+
+## [API 2]
+
+[etc.]
+
+## Key scenarios
+
+[If there are a suite of interacting APIs, show how they work together to solve the key scenarios described.]
+
+### Scenario 1
+
+[Description of the end-user scenario]
+
+```js
+// Sample code demonstrating how to use these APIs to address that scenario.
+```
+
+### Scenario 2
+
+[etc.]
+
+## Detailed design discussion
+
+### [Tricky design choice #1]
+
+[Talk through the tradeoffs in coming to the specific design point you want to make.]
+
+```js
+// Illustrated with example code.
+```
+
+[This may be an open question,
+in which case you should link to any active discussion threads.]
+
+### [Tricky design choice 2]
+
+[etc.]
+
+## Considered alternatives
+
+[This should include as many alternatives as you can,
+from high level architectural decisions down to alternative naming choices.]
+
+### [Alternative 1]
+
+[Describe an alternative which was considered,
+and why you decided against it.]
+
+### [Alternative 2]
+
+[etc.]
+
+## Stakeholder Feedback / Opposition
+
+[Implementors and other stakeholders may already have publicly stated positions on this work. If you can, list them here with links to evidence as appropriate.]
+
+- [Implementor A] : Positive
+- [Stakeholder B] : No signals
+- [Implementor C] : Negative
+
+[If appropriate, explain the reasons given by other implementors for their concerns.]
+
+## References & acknowledgements
+
+[Your design will change and be informed by many people; acknowledge them in an ongoing way! It helps build community and, as we only get by through the contributions of many, is only fair.]
+
+[Unless you have a specific reason not to, these should be in alphabetical order.]
+
+Many thanks for valuable feedback and advice from:
+
+- [Person 1]
+- [Person 2]
+- [etc.]
diff --git a/w3c.json b/w3c.json
@@ -0,0 +1,5 @@
+{
+    "group": 120428,
+    "contacts": ["hober", "TanviHacks", "erik-anderson", "wseltzer", "weiler"],
+    "repo-type": "cg-report"
+}
diff --git a/work-item.bs b/work-item.bs
@@ -0,0 +1,42 @@
+<pre class="metadata">
+<!-- The basics. Please change all of these values appropriately. -->
+Title: Privacy-Preserving Example API
+Shortname: shortname
+Repository: privacycg/shortname
+URL: https://privacycg.github.io/shortname/
+<!-- Replace NNNNN with your w3cid, which is the number at the end of the url when you navigate to https://www.w3.org/users/myprofile -->
+Editor: Your Name, w3cid NNNNN, Your Employer https://employer.example/, [email protected]
+Abstract: This specification defines the Example API, an exciting new method to invoke example methods from within a web browser.
+<!-- Choose a status. This is either a specification or a non-normative report. Several samples are commented out below. -->
+<!-- Status Text: This is a non-normative report. It is not a W3C standard nor is it on the W3C standards track. -->
+<!-- Status Text: This specification is intended to be migrated to the W3C standards track. It is not a W3C standard. -->
+<!-- Status Text: This specification is intended to be merged into the HTML Living Standard. It is neither a WHATWG Living Standard nor a W3C standard. -->
+<!-- Choose a license. You should pick the license used by your intended destination on the standards track. The two most probable licenses are provided as examples below. -->
+<!-- Text Macro: LICENSE <a href=http://www.w3.org/Consortium/Legal/2015/copyright-software-and-document>W3C Software and Document License</a> -->
+<!-- Text Macro: LICENSE <a href=https://creativecommons.org/licenses/by/4.0/>Creative Commons Attribution 4.0 International License</a> -->
+<!-- Leave the rest of this metadata alone. -->
+Group: privacycg
+Status: CG-DRAFT
+Level: None
+</pre>
+
+<section class="non-normative">
+<h2 id="intro">Introduction</h2>
+
+<em>This section is non-normative.</em>
+
+Blah blah blah.
+</section>
+
+<h2 id="infra">Infrastructure</h2>
+
+This specification depends on the Infra standard. [[!INFRA]]
+
+<h2 id="acknowledgements" class="no-num">Acknowledgements</h2>
+
+Many thanks to
+Some Body,
+Somebody Else,
+and
+A. Third Person
+for their feedback on this proposal.