Blame - CONTRIBUTING.md - external/github.com/gpuweb/gpuweb

blob: 29e679a09bf155c9b20bdb00d179147b0bcee02d [file] [log] [blame] [view]

Antonio Maiorano	1432db9	2025-04-26 16:18:54	[diff] [blame]	1	Contributions to specifications in this repository are intended to become part of
				2	Recommendation-track documents governed by the [W3C Patent
				3	Policy](https://www.w3.org/policies/patent-policy/) and [Software and Document
				4	License](https://www.w3.org/copyright/software-license-2023/). To contribute to the specifications,
				5	you must either participate in the relevant W3C Working Group or make a non-member patent licensing
				6	commitment.
				7
Kai Ninomiya	79fe4ad	2023-07-21 02:28:41	[diff] [blame]	8	# Building the WebGPU/WGSL specs
				9
				10	See [README.md](README.md) for procedural information about contributing.
				11
				12	See [wgsl/README.md](wgsl/README.md) for more details about building the WGSL spec.
				13
				14	## Setting up a working environment
				15
				16	### Using GitHub Codespaces
				17
				18	A GitHub Codespace is a very convenient way to make changes without setting up toolchains locally.
				19	It requires an internet connection and may be a little slower to build than your local machine.
				20
				21	> The Free and Pro plans for personal accounts include free use of GitHub Codespaces up to a fixed amount of usage every month.
				22
				23	For more info on GitHub Codespaces billing, see [this help page](https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces).
				24
				25	1. Fork the repository at <https://github.com/gpuweb/gpuweb/fork>
				26	1. On your fork:
				27	1. Click the big green "Code" button
				28	1. Switch to the "Codespaces" tab
				29	1. Click the "+" to create a new Codespace
				30
				31	This will open the Codespace in a tab. To get back to it:
				32
				33	1. Click the big green "Code" button (on your fork or the upstream repository gpuweb/gpuweb)
				34	1. Switch to the "Codespaces" tab
				35	1. Click on the name of your Codespace
				36	1. Using the built-in terminal:
				37	1. Create a branch: `git checkout -b my-new-change`
				38	1. See the "Building"/"Previewing" instructions below.
				39
				40	1. When you start a web server inside the Codespace, you'll get a notification on
				41	the editor page. Click on it to get to the web-visible URL for your server.
				42
				43	### Using the Dev Container locally
				44
				45	Please see <https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace-for-a-repository>.
				46
				47	### Using your local system without the Dev Container
				48
				49	On a local system, you'll need to install dependencies.
				50	To install all tools, run:
				51
				52	```bash
				53	./tools/install-dependencies.sh bikeshed diagrams wgsl
				54	```
				55
				56	(Alternatively, you can invoke `pip3`/`npx` directly, using the commands in
Emmanuel Ferdman	f21a2f6	2025-06-10 12:53:09	[diff] [blame]	57	[that script](tools/install-dependencies.sh).) More details:
Kai Ninomiya	79fe4ad	2023-07-21 02:28:41	[diff] [blame]	58
				59	The specifications are written using [Bikeshed](https://tabatkins.github.io/bikeshed).
				60	Installing Bikeshed is optional; if Bikeshed is not installed locally,
				61	the Bikeshed API will be used to generate the specification
				62	(but this is generally slower).
				63
				64	Diagrams generated using [Mermaid](https://mermaid-js.github.io/mermaid/).
				65	This isn't required unless you're modifying or creating diagrams.
				66
David Neto	27ed8cb	2025-10-15 18:32:11	[diff] [blame]	67	The WGSL spec uses some additional tools for language parsing.
				68	See [wgsl/README.md](wgsl/README.md) if you want to know more.
				69
				70	Some build steps for the WGSL spec modify the Python environment.
				71	If this is undesirable or not allowed in your situation, then create and use
				72	a [venv](https://docs.python.org/3/library/venv.html) virtual Python environment:
				73
				74	* As a one-time setup step, create a `venv` environment in a subdirectory:
				75
				76	# Run this from the root directory of the repository. Creates a subdir named `myenv`
				77	python -m venv myenv
				78
				79	* Then enter the virtual environment before running the WGSL build:
				80
				81	. myenv/bin/activate
				82	# Now you can build the WGSL spec in this shell
Kai Ninomiya	79fe4ad	2023-07-21 02:28:41	[diff] [blame]	83
				84	## Building this spec
				85
				86	To build all documents:
				87
				88	```bash
David Neto	27ed8cb	2025-10-15 18:32:11	[diff] [blame]	89	. myenv/bin/activate # Required only if using a Python virtual environment
Kai Ninomiya	79fe4ad	2023-07-21 02:28:41	[diff] [blame]	90	make -j
				91	```
				92
				93	To build just the WebGPU specification (`spec/index.html`):
				94
				95	```bash
				96	make -C spec index.html
				97	```
				98
				99	To build just the WGSL specification (`wgsl/index.html`):
				100
				101	```bash
David Neto	27ed8cb	2025-10-15 18:32:11	[diff] [blame]	102	. myenv/bin/activate # Required only if using a Python virtual environment
Kai Ninomiya	79fe4ad	2023-07-21 02:28:41	[diff] [blame]	103	make -C wgsl index.html
				104	```
				105
				106	Alternatively, `cd` into your target document's subdirectory, and call `make` or `make -j`.
				107
				108	Both `spec` and `wgsl` also have other targets in their `Makefile`s, which are documented inline.
				109
				110	The other documents in this repository (`correspondence` and `explainer`) can be built similarly.
				111
				112	## Previewing the spec
				113
				114	Launch a local web server to preview your spec changes, for example:
				115
				116	```bash
				117	python3 -m http.server
				118	```
				119
				120	(Add `-b localhost` if developing locally so the port won't be exposed to your network.)
				121
				122	or:
				123
				124	```bash
				125	npx http-server
				126	```
				127
				128	(Add `-a localhost` if developing locally so the port won't be exposed to your network.)