Skip to content

Commit fa46951

Browse files
darobindarobin
committed
finalised first pass on the docs
1 parent 3bde7f3 commit fa46951

File tree

13 files changed

+361
-84
lines changed

13 files changed

+361
-84
lines changed

‎generator/content/how-to/bikeshed.html

-8
This file was deleted.

‎generator/content/how-to/create.html

+114-1
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,118 @@
44
}
55
</script>
66
<p>
7-
Work in progress.
7+
There are essentially three cases in which you will want to handle your own repository of a
8+
specification.
89
</p>
10+
<dl>
11+
<dt>Relatively simple correction or change</dt>
12+
<dd>
13+
You have found an issue or have a relatively straightforward improvement to make to an
14+
existing specification. You do so by forking the specification, modifying it in a branch, and
15+
making a pull-request against the original. No specific knowledge is required beyond the
16+
basics of git and GitHub, and the format used for specifications (for which links are provided
17+
below).This is exactly the same process as for any open source project on GitHub.
18+
</dd>
19+
<dt><a href="#forking">Forking</a></dt>
20+
<dd>
21+
You disagree with part of an existing specification or you wish to propose a relatively large
22+
new feature or change of behaviour. It is likely that your proposal would not be accepted
23+
immediately but would require discussion in the community, likely leading to some changes
24+
along the way. In this case you will want to not only fork the specification, but also
25+
publish it on WebSpecs so that others can review it. This is explained below.
26+
</dd>
27+
<dt><a href="#scratch">Starting From Scratch</a></dt>
28+
<dd>
29+
You have a completely new idea for a specification and you wish to publish it as a WebSpec.
30+
Simply follow the instructions in the corresponding section below and you will be good to go.
31+
Note that before embarking on this it is <strong>strongly</strong> recommended that you first
32+
discuss the issue on <a href="http://discourse.specifiction.org/">Discourse</a> as it is
33+
likely that you will receive useful feedback and guidance from the community there that could
34+
save you a lot of work down the line.
35+
</dd>
36+
</dl>
37+
<section>
38+
<h2 id="forking">Forking</h2>
39+
<p>
40+
Simply fork the repository for the specification of interest into a new one that you have
41+
write access to. It absolutely does not need to be under the
42+
<a href="https://github.com/webspecs/">WebSpecs</a> organisation at GitHub. It doesn't matter
43+
if you are forking a fork (of a fork of a fork), simply pick the most logical starting point
44+
for you.
45+
</p>
46+
<p>
47+
Check it out and create a new topic branch. The rule for branches is very simple:
48+
<code>master</code> is for things that have shipped in implementations and are well-tested, and
49+
<code>develop</code> is for stuff that doesn't yet pass tests but that does have clear
50+
implementation commitments from browser vendors. If not in either of the previous two
51+
categories, just pick a self-descriptive name that you like.
52+
</p>
53+
<p>
54+
You will then need to edit your specification. The file you will want to change will typically
55+
be called <code>index.bs</code> (but other <code>*.bs</code> variants are possible). The
56+
format is "Bikeshed", a Markdown flavour that is popular for specification writing and for
57+
which you can <a href="https://github.com/tabatkins/bikeshed/tree/master/docs">read
58+
documentation online</a>. If you are familiar with Markdown you ought to find Bikeshed easy.
59+
If you are of those who hate Markdown, do not despair: an alternative HTML-based format will
60+
soon be made available as well.
61+
</p>
62+
<p>
63+
It is recommended to have a copy of Bikeshed installed (preferably in a directory parallel to
64+
the specifications you are working on) but it is not required.
65+
</p>
66+
<p>
67+
Make changes, push them, etc. Once you want to publish your work to the community, simply
68+
make a pull-request against <a href="https://github.com/webspecs/the-index">the-index</a>.
69+
That is the document that sits at the root of
70+
<a href="https://specs.webplatform.org/">https://specs.webplatform.org/</a> and which drives
71+
the automatic publishing system. When your PR is reviewed, you will be given simple
72+
instructions to ensure that your fork is automatically published whenever you make changes to
73+
it. Once your PR is accepted, the WebSpecs index will be updated and your specification will
74+
be published.
75+
</p>
76+
<p>
77+
That's it!
78+
</p>
79+
</section>
80+
<section>
81+
<h2 id="scratch">Starting From Scratch</h2>
82+
<p>
83+
The process for starting from scratch is substantially the same as the process for forking,
84+
except of course that you have to set up the initial repository yourself.
85+
</p>
86+
<p>
87+
To begin with, create a repository in the usual way, wherever you want. Pick a name for it
88+
that is descriptive (avoid silly, because that tends to stick). Clone it locally, and create
89+
a branch according to the guidelines presented in the previous section.
90+
</p>
91+
<p>
92+
You will want to install the <code>webspec</code> tool, which is straightforward: <code>npm
93+
install -g webspec</code>. Note: in the close future this tool will be replace with a simpler
94+
Web interface that carries out the same basic tasks.
95+
</p>
96+
<p>
97+
As indicated in the previous section, it is a good idea to clone Bikeshed in a directory
98+
parallel to the ones in which you edit specifications. While not required (the source gets
99+
regenerated at publish time anyway) it allows you to check that you don't have errors in your
100+
draft.
101+
</p>
102+
<p>
103+
While at the root of your specification's directory, type <code>webspec new</code> and follow
104+
the instructions. (Note: the current default license of "CC0" is likely to change.)
105+
</p>
106+
<p>
107+
This should give you a specification that's ready to go! At this point you are ready to make
108+
a pull-request against <a href="https://github.com/webspecs/the-index">the-index</a> and
109+
follow the subsequent instructions. You're good to go!
110+
</p>
111+
</section>
112+
<section>
113+
<h2 id="help">Getting Help</h2>
114+
<p>
115+
The easiest way to get help is to join us on IRC, channel
116+
<a href="irc://freenode.net/webspecs">#webspecs on the Freenode.net network</a>. It's a
117+
helpful bunch. If you are certain that the issue is with a tool, file an issue on GitHub.
118+
There are more options listed in <a href="/docs/#community">Community &amp; Support</a>, and
119+
if all else fails you can email <a href="mailto:[email protected]">Robin</a>.
120+
</p>
121+
</section>

‎generator/content/how-to/discuss.html

+42-1
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,47 @@ <h2>Reporting Bugs</h2>
3939
<section>
4040
<h2>Discussing New Ideas</h2>
4141
<p>
42-
42+
For obvious reasons, completely new ideas cannot be discussed as bugs against a given
43+
specification since presumably that specification does not exist in the first place.
44+
</p>
45+
<p>
46+
Even in the case in which there happens to be an existing repository, if the novel idea you
47+
wish to discuss is broad enough in its reach it can be useful to bring it to the full
48+
community rather than restrict its discussion to the smaller number of people who will be
49+
tracking issues against a specific document.
50+
</p>
51+
<p>
52+
In either case, the best place at which to conduct such a discussion is at the community's
53+
Discourse instance at
54+
<a href="http://discourse.specifiction.org/">http://discourse.specifiction.org/</a>. (Note that
55+
it is expected to move to https://discourse.webplatform.org/ in the relatively close future.)
56+
</p>
57+
<p>
58+
If you have used Web forums before and you still want to claw your own eyes out from the
59+
distress it has caused you, do not be alarmed. Discourse is forums reinvented. It is pleasant
60+
to use; in fact you will likely want to come back.
61+
</p>
62+
<p>
63+
Simply create an account there and get started. Beginning users have a few restrictions on
64+
their accounts (such as number of links per post) in order to limit spam, but those get lifted
65+
quickly as you interact with others (and you can ask the admins to bump your karma).
66+
</p>
67+
<p>
68+
Do not be afraid. No one will be mean to you if your post contains an error, or if you are
69+
suggesting something that has been explored and abandoned before. There are many Web standards
70+
and they have a rich history; no one is expected to know everything, and we would rather have
71+
good ideas at the cost of a little noise than the other way around.
72+
</p>
73+
<p>
74+
There are only a few rules for participation. First, exchanges there are under our strict
75+
<a href="/docs/policy/anti-jerk.html">anti-jerk policy</a>. If you are mean to others there will
76+
be consequences, if you see others being mean please report that to the admins (posts can be
77+
flagged). Second, the forum is for discussion of new ideas or problems with Web standards, not
78+
to ask questions about how to use something or how to make a browser work with your code.
79+
There's StackOverflow for that!
80+
</p>
81+
<p>
82+
That's it! Several of the discussions there have already influenced existing and upcoming
83+
standards — all it takes for more of the same to happen is for you to join and talk.
4384
</p>
4485
</section>

‎generator/content/how-to/index.html

+1-1
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
You want to jump in and actually write some text, either from scratch or as a modification to
1919
someone else’s work. The details are on this page.
2020
</dd>
21-
<dt><a href="bikeshed.html">Bikeshed — the syntax of WebSpecs</a></dt>
21+
<dt><a href="https://github.com/tabatkins/bikeshed/tree/master/docs">Bikeshed — the syntax of WebSpecs</a></dt>
2222
<dd>
2323
WebSpecs are written using a Markdown flavour known as “Bikeshed” that happens to have a lot
2424
of tricks up its sleeve that comes in handy when producing a specification. There’s a lot that

‎generator/templates/default.html

+2-2
Original file line numberDiff line numberDiff line change
@@ -37,9 +37,9 @@ <h1>XXX</h1>
3737
<p>
3838
<a href="/">specs</a>
3939
•
40-
<a href="http://creativecommons.org/publicdomain/zero/1.0/" rel="license">CC0</a>
40+
<a href="http://www.w3.org/Consortium/Legal/copyright-software" rel="license">license</a>
4141
•
42-
<a href="https://github.com/webspecs/docs">⋔ me</a>
42+
<a href="https://github.com/webspecs/docs">fork me</a>
4343
•
4444
<a href="/docs/policy/principles.html">principles</a>
4545
•

‎how-to/bikeshed.html

-48
This file was deleted.

‎how-to/create.html

+121-4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
<!DOCTYPE html><html lang="en"><head>
1+
<!DOCTYPE html><!--
2+
WARNING!
3+
Do not edit this file! (Unless you're editing the template which generates this comment :) as
4+
it is autogenerated and will get overwritten. Edit the source documents under /content/ instead.
5+
--><html lang="en"><head>
26
<meta charset="utf-8">
37
<meta name="viewport" content="width=device-width">
48
<title>Creating Specifications | Web Platform Specs</title>
@@ -25,17 +29,130 @@ <h1 class="onlyTitle">Creating Specifications</h1>
2529
<a href="https://github.com/webspecs/docs">fork me</a>
2630
</nav>
2731
<div class="content"><p>
28-
Work in progress.
32+
There are essentially three cases in which you will want to handle your own repository of a
33+
specification.
2934
</p>
35+
<dl>
36+
<dt>Relatively simple correction or change</dt>
37+
<dd>
38+
You have found an issue or have a relatively straightforward improvement to make to an
39+
existing specification. You do so by forking the specification, modifying it in a branch, and
40+
making a pull-request against the original. No specific knowledge is required beyond the
41+
basics of git and GitHub, and the format used for specifications (for which links are provided
42+
below).This is exactly the same process as for any open source project on GitHub.
43+
</dd>
44+
<dt><a href="#forking">Forking</a></dt>
45+
<dd>
46+
You disagree with part of an existing specification or you wish to propose a relatively large
47+
new feature or change of behaviour. It is likely that your proposal would not be accepted
48+
immediately but would require discussion in the community, likely leading to some changes
49+
along the way. In this case you will want to not only fork the specification, but also
50+
publish it on WebSpecs so that others can review it. This is explained below.
51+
</dd>
52+
<dt><a href="#scratch">Starting From Scratch</a></dt>
53+
<dd>
54+
You have a completely new idea for a specification and you wish to publish it as a WebSpec.
55+
Simply follow the instructions in the corresponding section below and you will be good to go.
56+
Note that before embarking on this it is <strong>strongly</strong> recommended that you first
57+
discuss the issue on <a href="http://discourse.specifiction.org/">Discourse</a> as it is
58+
likely that you will receive useful feedback and guidance from the community there that could
59+
save you a lot of work down the line.
60+
</dd>
61+
</dl>
62+
<section>
63+
<h2 id="forking">Forking</h2>
64+
<p>
65+
Simply fork the repository for the specification of interest into a new one that you have
66+
write access to. It absolutely does not need to be under the
67+
<a href="https://github.com/webspecs/">WebSpecs</a> organisation at GitHub. It doesn't matter
68+
if you are forking a fork (of a fork of a fork), simply pick the most logical starting point
69+
for you.
70+
</p>
71+
<p>
72+
Check it out and create a new topic branch. The rule for branches is very simple:
73+
<code>master</code> is for things that have shipped in implementations and are well-tested, and
74+
<code>develop</code> is for stuff that doesn't yet pass tests but that does have clear
75+
implementation commitments from browser vendors. If not in either of the previous two
76+
categories, just pick a self-descriptive name that you like.
77+
</p>
78+
<p>
79+
You will then need to edit your specification. The file you will want to change will typically
80+
be called <code>index.bs</code> (but other <code>*.bs</code> variants are possible). The
81+
format is "Bikeshed", a Markdown flavour that is popular for specification writing and for
82+
which you can <a href="https://github.com/tabatkins/bikeshed/tree/master/docs">read
83+
documentation online</a>. If you are familiar with Markdown you ought to find Bikeshed easy.
84+
If you are of those who hate Markdown, do not despair: an alternative HTML-based format will
85+
soon be made available as well.
86+
</p>
87+
<p>
88+
It is recommended to have a copy of Bikeshed installed (preferably in a directory parallel to
89+
the specifications you are working on) but it is not required.
90+
</p>
91+
<p>
92+
Make changes, push them, etc. Once you want to publish your work to the community, simply
93+
make a pull-request against <a href="https://github.com/webspecs/the-index">the-index</a>.
94+
That is the document that sits at the root of
95+
<a href="https://specs.webplatform.org/">https://specs.webplatform.org/</a> and which drives
96+
the automatic publishing system. When your PR is reviewed, you will be given simple
97+
instructions to ensure that your fork is automatically published whenever you make changes to
98+
it. Once your PR is accepted, the WebSpecs index will be updated and your specification will
99+
be published.
100+
</p>
101+
<p>
102+
That's it!
103+
</p>
104+
</section>
105+
<section>
106+
<h2 id="scratch">Starting From Scratch</h2>
107+
<p>
108+
The process for starting from scratch is substantially the same as the process for forking,
109+
except of course that you have to set up the initial repository yourself.
110+
</p>
111+
<p>
112+
To begin with, create a repository in the usual way, wherever you want. Pick a name for it
113+
that is descriptive (avoid silly, because that tends to stick). Clone it locally, and create
114+
a branch according to the guidelines presented in the previous section.
115+
</p>
116+
<p>
117+
You will want to install the <code>webspec</code> tool, which is straightforward: <code>npm
118+
install -g webspec</code>. Note: in the close future this tool will be replace with a simpler
119+
Web interface that carries out the same basic tasks.
120+
</p>
121+
<p>
122+
As indicated in the previous section, it is a good idea to clone Bikeshed in a directory
123+
parallel to the ones in which you edit specifications. While not required (the source gets
124+
regenerated at publish time anyway) it allows you to check that you don't have errors in your
125+
draft.
126+
</p>
127+
<p>
128+
While at the root of your specification's directory, type <code>webspec new</code> and follow
129+
the instructions. (Note: the current default license of "CC0" is likely to change.)
130+
</p>
131+
<p>
132+
This should give you a specification that's ready to go! At this point you are ready to make
133+
a pull-request against <a href="https://github.com/webspecs/the-index">the-index</a> and
134+
follow the subsequent instructions. You're good to go!
135+
</p>
136+
</section>
137+
<section>
138+
<h2 id="help">Getting Help</h2>
139+
<p>
140+
The easiest way to get help is to join us on IRC, channel
141+
<a href="irc://freenode.net/webspecs">#webspecs on the Freenode.net network</a>. It's a
142+
helpful bunch. If you are certain that the issue is with a tool, file an issue on GitHub.
143+
There are more options listed in <a href="/docs/#community">Community &amp; Support</a>, and
144+
if all else fails you can email <a href="mailto:[email protected]">Robin</a>.
145+
</p>
146+
</section>
30147
</div>
31148
<footer>
32149
<div class="subfooter">
33150
<p>
34151
<a href="/">specs</a>
35152
•
36-
<a href="http://creativecommons.org/publicdomain/zero/1.0/" rel="license">CC0</a>
153+
<a href="http://www.w3.org/Consortium/Legal/copyright-software" rel="license">license</a>
37154
•
38-
<a href="https://github.com/webspecs/docs">⋔ me</a>
155+
<a href="https://github.com/webspecs/docs">fork me</a>
39156
•
40157
<a href="/docs/policy/principles.html">principles</a>
41158
•

0 commit comments

Comments
 (0)