8000 [meta] Linebreak properly · tcaptan-cr/csswg-drafts@5f9b089 · GitHub
Skip to content

Commit 5f9b089

Browse files
tabatkinstabatkins
committed
[meta] Linebreak properly
1 parent 0ae5a16 commit 5f9b089

File tree

1 file changed

+111
-70
lines changed

1 file changed

+111
-70
lines changed

‎CONTRIBUTING.md‎

Lines changed: 111 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
# Contributor Guidelines
22

3-
Thank you for your interest in contributing to the [CSS Working Group](https://www.w3.org/Style/CSS/)
4-
drafts!
3+
Thank you for your interest in contributing
4+
to the [CSS Working Group](https://www.w3.org/Style/CSS/) drafts!
55

6-
Contributions to this repository are intended to become part of Recommendation-track
7-
documents governed by the:
6+
Contributions to this repository
7+
are intended to become part of Recommendation-track documents
8+
governed by the:
89

910
* [W3C Patent Policy](https://www.w3.org/Consortium/Patent-Policy-20200915/)
1011
* [Software and Document License](https://www.w3.org/Consortium/Legal/copyright-software)
1112

12-
To make substantive contributions to specifications, you must either participate
13-
in the relevant W3C Working Group or make a non-member patent licensing commitment.
13+
To make substantive contributions to specifications,
14+
you must either participate in the relevant W3C Working Group
15+
or make a non-member patent licensing commitment.
1416

1517
## Issue disclosure and discussion
1618

@@ -19,79 +21,115 @@ The first step for any substantive contribution is to either:
1921
1. [Find an existing issue](https://github.com/w3c/csswg-drafts/issues) directly related to the contribution
2022
2. [Add a new issue](https://github.com/w3c/csswg-drafts/issues/new)
2123

22-
Issues are where individual reports and Working Group discussions come together such
23-
that the eventual consensus can be turned into official specification language.
24+
Issues are where individual reports and Working Group discussions
25+
come together such that the eventual consensus
26+
can be turned into official specification language.
2427

25-
If you are familiar with a [GitHub-based pull request contribution workflow](https://help.github.com/articles/about-pull-requests/),
26-
please note that **most issues are subject to quite a bit of discussion** before
27-
they are ready for a pull request with specific wording changes. Please ensure
28-
the full problem space of the issue is explored in the discussion, and that
29-
consensus has been reached by the participants, before drafting a pull request.
28+
If you are familiar with a
29+
[GitHub-based pull request contribution workflow](https://help.github.com/articles/about-pull-requests/),< 8000 /div>
30+
please note that **most issues are subject to quite a bit of discussion**
31+
before they are ready for a pull request with specific wording changes.
32+
Please ensure the full problem space of the issue is explored in the discussion,
33+
and that consensus has been reached by the participants,
34+
before drafting a pull request.
3035

3136
## Normative and/or substantive contributions
3237

33-
The CSS Working Group operates via the consensus of its membership, and discusses
34-
all significant matters prior to implementation.
35-
36-
The Editors responsible for a particular spec are responsible for triaging their
37-
issues on a regular basis; however note that sometimes this can take awhile
38-
(anywhere from a few days to a few years) depending on the complexity of the
39-
issue and the work schedules of people involved--this does not mean we are
40-
ignoring the issue.
41-
42-
When issues need WG discussion or approval, WG members should label the issue
43-
'Agenda+' to bring it to the Working Group's attention. Unfortunately,
44-
GitHub doesn't allow labelling permissions without repository write permissions,
45-
so if you believe an issue is urgent or discussion has stalled for awhile and
46-
the WG's attention is needed to move forward, ask one of the Editors to flag it.
47-
48-
In general, you should not directly commit changes to a draft unless you are an
49-
Editor of that draft, or have their explicit permission. If you are not an
50-
Editor of a draft, but wish to contribute changes, the best practice is to either
51-
work directly with an Editor to review proposed text, or file your proposal as a
52-
pull request (PR) originating from your own fork. Substantive changes
53-
need WG consensus, not merely Editor agreement; typographic error and markup fixes
54-
are generally okay to commit, but any substantive changes should have
55-
clear WG consensus. Substantial changes or additions to non-normative text
38+
The CSS Working Group operates via the consensus of its membership,
39+
and discusses all significant matters prior to implementation.
40+
41+
The Editors responsible for a particular spec
42+
are responsible for triaging their issues on a regular basis;
43+
however note that sometimes this can take awhile
44+
(anywhere from a few days to a few years)
45+
depending on the complexity of the issue
46+
and the work schedules of people involved ―
47+
this does not mean we are ignoring the issue.
48+
49+
When issues need WG discussion or approval,
50+
WG members should label the issue 'Agenda+'
51+
to bring it to the Working Group's attention.
52+
Unfortunately, GitHub doesn't allow labelling permissions
53+
without repository write permissions,
54+
so if you believe an issue is urgent
55+
or discussion has stalled for awhile
56+
and the WG's attention is needed to move forward,
57+
ask one of the Editors to flag it.
58+
59+
In general, you should not directly commit changes to a draft
60+
unless you are an Editor of that draft,
61+
or have their explicit permission.
62+
If you are not an Editor of a draft,
63+
but wish to contribute changes,
64+
the best practice is to either work directly with an Editor to review proposed text,
65+
or file your proposal as a pull request (PR)
66+
originating from your own fork.
67+
Substantive changes need WG consensus,
68+
not merely Editor agreement;
69+
typographic error and markup fixes are generally okay to commit,
70+
but any substantive changes should have clear WG consensus.
71+
Substantial changes or additions to non-normative text
5672
should still have clear Editor approval.
5773

58-
In any case, WG consensus is expected prior to merging changes, and consensus is
59-
determined by the Chairs (not self-assessed) via synchronous decisions during
60-
meetings, and occasionally via async CFCs. Some degree of discretion is afforded
61-
to Editors to make changes prior to WG consensus, particularly early in a spec or
62-
feature's lifecycle, although Editors must confirm those changes with the WG
63-
prior to republishing on TR. References to the discussion and the WG consensus
64-
should be placed in the issue or commit. Agreement from an Editor in an issue
65-
is not a substitute for WG consensus.
66-
67-
The Working Group, aside from managing issues on GitHub, mainly discusses
68-
specifications and requests on [the www-style public mailing list](https://lists.w3.org/Archives/Public/www-style/),
69-
and in CSSWG meetings, whose minutes are posted to www-style.
74+
In any case,
75+
WG consensus is expected prior to merging changes,
76+
and consensus is determined by the Chairs
77+
(not self-assessed)
78+
via synchronous decisions during meetings,
79+
and occasionally via async CFCs.
80+
Some degree of discretion is afforded to Editors
81+
to make changes prior to WG consensus,
82+
particularly early in a spec or feature's lifecycle,
83+
although Editors must confirm those changes with the WG
84+
prior to republishing on TR.
85+
References to the discussion and the WG consensus
86+
should be placed in the issue or commit.
87+
Agreement from an Editor in an issue is not a substitute for WG consensus.
88+
89+
The Working Group, aside from managing issues on GitHub,
90+
mainly discusses specifications and requests on
91+
[the www-style public mailing list](https://lists.w3.org/Archives/Public/www-style/),
92+
and in CSSWG meetings,
93+
whose minutes are posted to www-style.
7094

7195
### After discussion
7296

73-
Once the Working Group has come to a consensus, the editor may draft up and
74-
commit the relevant changes for review by other contributors or a contributor
75-
may file a pull request against the issue for review by the editor(s). Since
76-
specification wording is tricky, it is strongly recommended that the editors
77-
of that particular spec be involved, either as originator or as reviewer, in
78-
any changes. We also encourage other participants in the issue discussion to
79-
review the changes and request corrections or improvements as necessary.
80-
81-
Please follow the [Pull Request template](https://github.com/w3c/csswg-drafts/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
97+
Once the Working Group has come to a consensus,
98+
the editor may draft up and commit the relevant changes
99+
for review by other contributors
100+
or a contributor may file a pull request against the issue
101+
for review by the editor(s).
102+
Since specification wording is tricky,
103+
it is strongly recommended that the editors of that particular spec be involved,
104+
either as originator or as reviewer,
105+
in any changes.
106+
We also encourage other participants in the issue discussion
107+
to review the changes
108+
and request corrections or improvements as necessary.
109+
110+
Please follow the
111+
[Pull Request template](https://github.com/w3c/csswg-drafts/blob/master/.github/PULL_REQUEST_TEMPLATE.md)
82112
when contributing to the repository.
83113

84114
### Tests
85115

86116
For normative changes for any specification in
87-
[CR or later](https://www.w3.org/Style/CSS/current-work) as well as the pre-CR specifications listed
88-
below, a corresponding [web-platform-tests](https://github.com/web-platform-tests/wpt) PR must be
89-
provided, except if testing is not practical; for other specifications it is usually appreciated.
90-
91-
Typically, both PRs will be merged at the same time. Note that a test change that contradicts the
92-
spec should not be merged before the corresponding spec change. If testing is not practical, please
93-
explain why and if appropriate [file an issue](https://github.com/web-platform-tests/wpt/issues/new)
94-
to follow up later. Add the `type:untestable` or `type:missing-coverage` label as appropriate.
117+
[CR or later](https://www.w3.org/Style/CSS/current-work)
118+
as well as the pre-CR specifications listed below,
119+
a corresponding
120+
[web-platform-tests](https://github.com/web-platform-tests/wpt)
121+
PR must be provided,
122+
except if testing is not practical;
123+
for other specifications it is usually appreciated.
124+
125+
Typically, both PRs will be merged at the same time.
126+
Note that a test change that contradicts the spec
127+
should not be merged before the corresponding spec change.
128+
If testing is not practical,
129+
please explain why and if appropriate
130+
[file an issue](https://github.com/web-platform-tests/wpt/issues/new)
131+
to follow up later.
132+
Add the `type:untestable` or `type:missing-coverage` label as appropriate.
95133

96134
The pre-CR specifications with this testing requirement are currently:
97135

@@ -100,14 +138,17 @@ The pre-CR specifications with this testing requirement are currently:
100138

101139
## Non-substantive contributions
102140

103-
For simple spelling, grammar, or markup fixes unrelated to the substance of a
104-
specification, issuing a pull request without a corresponding issue is acceptable.
141+
For simple spelling, grammar, or markup fixes
142+
unrelated to the substance of a specification,
143+
issuing a pull request without a corresponding issue is acceptable.
105144

106145
## Further information
107146

108-
Specification source files are in [Bikeshed format](https://tabatkins.github.io/bikeshed/).
147+
Specification source files are in [Bikeshed format](https://speced.github.io/bikeshed/).
109148
The CSSWG wiki has more information on other [CSSWG tooling](https://wiki.csswg.org/tools).
110149

111150
See [about:csswg](http://fantasai.inkedblade.net/weblog/2011/inside-csswg/)
112-
for more information on how the CSSWG operates, delegates authority, and
113-
makes decisions. Someday maybe we'll also have a useful official website.
151+
for more information on how the CSSWG operates,
152+
delegates authority,
153+
and makes decisions.
154+
Someday maybe we'll also have a useful official website.

0 commit comments

Comments
 (0)