Skip to content

Commit e24624b

Browse files
authored
Update README.md with Development guidance (#852)
- Add a new Development section to integrate tools - Expand Pull Requests guidance - Add a cool WebNN logo!
1 parent 3032b25 commit e24624b

File tree

1 file changed

+38
-8
lines changed

1 file changed

+38
-8
lines changed

README.md

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,59 @@
11
[![build](https://github.com/webmachinelearning/webnn/actions/workflows/auto-publish.yml/badge.svg)](https://github.com/webmachinelearning/webnn/actions)
22

3+
![](https://webmachinelearning.github.io/logos/webnn/logo-webnn-white.png)
4+
35
# Web Neural Network API
46

57
This repository hosts the [Web Neural Network API](https://www.w3.org/TR/webnn/)
68
being worked on in the
79
[Web Machine Learning Working Group](https://www.w3.org/groups/wg/webmachinelearning).
810

9-
## Pull requests
11+
To join this Working Group, please see these [instructions](https://webmachinelearning.github.io/community/#join).
1012

11-
To propose a change, update `index.bs` and submit your PR. The `index.html` file is automatically built and deployed upon merge.
13+
## Development
1214

13-
The spec is written using [Bikeshed](https://tabatkins.github.io/bikeshed). Please refer to the [Bikeshed Documentation](https://tabatkins.github.io/bikeshed/) for the Bikeshed syntax.
15+
This section describes the process for building this specification on your local computer for development and testing purposes. You may want to do this before you submit a [Pull Request](#pull-requests) to catch possible build issues early.
1416

15-
For testing purposes, you can generate the spec locally:
17+
The first step is to clone the repo:
1618

17-
If you have bikeshed [installed locally](https://tabatkins.github.io/bikeshed/#installing), you can generate the specification locally with:
19+
```
20+
prompt> git clone https://github.com/webmachinelearning/webnn
21+
```
22+
23+
Next, install the makefile dependencies:
1824

1925
```
20-
prompt> make
26+
prompt> cd tools
27+
prompt> npm install
28+
prompt> cd ..
2129
```
2230

23-
This simply runs bikeshed on the `index.bs` file.
31+
Now you can choose between the two options:
32+
33+
- [Install Bikeshed locally](https://speced.github.io/bikeshed/#install-final) (works offline, faster build) and run:
34+
35+
```
36+
prompt> make
37+
```
2438

25-
Otherwise, you can use the [bikeshed Web API](https://tabatkins.github.io/bikeshed/#remote):
39+
- Or use the [Bikeshed HTTP API](https://speced.github.io/bikeshed/#remote) (requires internet, slower build):
2640

2741
```
2842
prompt> make online=1
2943
```
44+
45+
In both the cases, the makefile runs [tools](tools) to check the source formatting and catch common errors, and then uses Bikeshed to convert the `index.bs` source file to an `index.html` output file.
46+
47+
If the build is clean you can open the `index.html` file in your browser to view it in all its glory! If you're happy with what you see, congratulations! You can proceed to submit a [Pull Request](#pull-requests).
48+
49+
## Pull Requests
50+
51+
First, please read the [contributing guidelines](CONTRIBUTING.md).
52+
53+
The spec is written using [Bikeshed](https://speced.github.io/bikeshed/) spec-generating tool. Please refer to the [Bikeshed Documentation](https://speced.github.io/bikeshed/) for the Bikeshed syntax and [coding conventions](docs/SpecCodingConventions.md) specific to this specification.
54+
55+
To propose a change to the specification, you are only required to update the `index.bs` source file authored in Bikeshed syntax.
56+
57+
Before you submit a PR, it is recommended to test your changes locally (see [Development](#development)). If your local build is clean, you can proceed to submit the PR. If you want to submit a WIP PR that still contains errors or is incomplete, please [convert the PR to a draft](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request#converting-a-pull-request-to-a-draft). As a convention, please [link the PR to an existing issue](https://graphite.dev/guides/how-to-link-pull-requests-to-github-issues) for [non-editorial changes](CONTRIBUTING.md#type-of-change).
58+
59+
After you submit the PR, it is first automatically checked with [GitHub Actions CI/CD](.github/workflows/auto-publish.yml) for common issues and then reviewed by group participants. After adequate review and approvals, the PR is merged and a new version of the specification is deployed at https://www.w3.org/TR/webnn/ ([history](https://www.w3.org/standards/history/webnn/)).

0 commit comments

Comments
 (0)