From 6f3fb06fa4b1fb8e5ec1f6d3ba73903238fd63e8 Mon Sep 17 00:00:00 2001
From: Martin Thomson <mt@lowentropy.net>
Date: Wed, 4 Dec 2024 03:45:31 +1100
Subject: [PATCH] Readme and more (#515)

---
 .gitignore |  7 +++++--
 Makefile   | 21 ++++++++++++++++-----
 README.md  | 17 +++++++++--------
 3 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/.gitignore b/.gitignore
index 178d4f29..f4f4a27d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
-build/
-out/
 *.sublime-*
+*.swp
+*~
+/.venv/
+/build/
+/out/
diff --git a/Makefile b/Makefile
index d500846f..f34778a3 100644
--- a/Makefile
+++ b/Makefile
@@ -1,15 +1,26 @@
-specs = $(patsubst %.bs,build/%.html,$(wildcard *.bs))
+specs := $(patsubst %.bs,build/%.html,$(wildcard *.bs))
+VENV := .venv
+bikeshed := $(VENV)/bin/bikeshed
 
-.PHONY: all clean
+.PHONY: all clean dist-clean
 .SUFFIXES: .bs .html
 
 all: $(specs)
 
 clean:
-	rm -rf build *~
+	-rm -rf build *~
+
+dist-clean: clean
+	-rm -rf $(VENV)
 
 build:
 	mkdir -p build
 
-build/%.html: %.bs Makefile build
-	bikeshed --die-on=fatal spec $< $@
+$(VENV):
+	python3 -m venv $(VENV)
+
+$(bikeshed): $(VENV)
+	$(VENV)/bin/pip install bikeshed
+
+build/%.html: %.bs build $(bikeshed)
+	$(bikeshed) --die-on=fatal spec $< $@
diff --git a/README.md b/README.md
index 0161a059..7280ac6c 100644
--- a/README.md
+++ b/README.md
@@ -1,14 +1,15 @@
-design-principles
-=================
+# Web Platform Design Principles
 
-This is a repository for a (proposed) set of general design principles
+A set of design principles to be used when designing web platform technologies. These principles have been collected by the [Technical Architecture Group](https://www.w3.org/2001/tag/) and developed along with the [Ethical Web principles](https://github.com/w3ctag/ethical-web-principles/).
 
-Building
---------
 
-You will need [GNU Make](https://www.gnu.org/software/make/) and [Bikeshed](https://pypi.org/project/bikeshed/).
+# Building
 
-With those dependencies, simply invoke this command to build the document:
+You will need [GNU Make](https://www.gnu.org/software/make/) and Python 3.
 
-    make
+With those dependencies, simply invoke `make` to build the document.
 
+
+# Contributing
+
+Contributions are welcome to anyone who follows [our code of conduct](https://www.w3.org/Consortium/cepc/).