Contributor Guidelines

Thank you for your interest in contributing to the CSS Working Group drafts!

Contributions to this repository are intended to become part of Recommendation-track documents governed by the:

W3C Patent Policy
Software and Document License

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

Issue disclosure and discussion

The first step for any substantive contribution is to either:

Find an existing issue directly related to the contribution
Add a new issue

Issues are where individual reports and Working Group discussions come together such that the eventual consensus can be turned into official specification language.

If you are familiar with a GitHub-based pull request contribution workflow, please note that most issues are subject to quite a bit of discussion before they are ready for a pull request with specific wording changes. Please ensure the full problem space of the issue is explored in the discussion, and that consensus has been reached by the participants, before drafting a pull request.

Normative and/or substantive contributions

The CSS Working Group operates via the consensus of its membership, and discusses all significant matters prior to implementation.

The Editors responsible for a particular spec are responsible for triaging their issues on a regular basis; however note that sometimes this can take awhile (anywhere from a few days to a few years) depending on the complexity of the issue and the work schedules of people involved ― this does not mean we are ignoring the issue.

When issues need WG discussion or approval, WG members should label the issue 'Agenda+' to bring it to the Working Group's attention. Unfortunately, GitHub doesn't allow labelling permissions without repository write permissions, so if you believe an issue is urgent or discussion has stalled for awhile and the WG's attention is needed to move forward, ask one of the Editors to flag it.

In general, you should not directly commit changes to a draft unless you are an Editor of that draft, or have their explicit permission. If you are not an Editor of a draft, but wish to contribute changes, the best practice is to either work directly with an Editor to review proposed text, or file your proposal as a pull request (PR) originating from your own fork. Substantive changes need WG consensus, not merely Editor agreement; typographic error and markup fixes are generally okay to commit, but any substantive changes should have clear WG consensus. Substantial changes or additions to non-normative text should still have clear Editor approval.

In any case, WG consensus is expected prior to merging changes, and consensus is determined by the Chairs (not self-assessed) via synchronous decisions during meetings, and occasionally via async CFCs. Some degree of discretion is afforded to Editors to make changes prior to WG consensus, particularly early in a spec or feature's lifecycle, although Editors must confirm those changes with the WG prior to republishing on TR. References to the discussion and the WG consensus should be placed in the issue or commit. Agreement from an Editor in an issue is not a substitute for WG consensus.

The Working Group, aside from managing issues on GitHub, mainly discusses specifications and requests on the www-style public mailing list, and in CSSWG meetings, whose minutes are posted to www-style.

After discussion

Once the Working Group has come to a consensus, the editor may draft up and commit the relevant changes for review by other contributors or a contributor may file a pull request against the issue for review by the editor(s). Since specification wording is tricky, it is strongly recommended that the editors of that particular spec be involved, either as originator or as reviewer, in any changes. We also encourage other participants in the issue discussion to review the changes and request corrections or improvements as necessary.

Please follow the Pull Request template when contributing to the repository.

Tests

For normative changes for any specification in CR or later as well as the pre-CR specifications listed below, a corresponding web-platform-tests PR must be provided, except if testing is not practical; for other specifications it is usually appreciated.

Typically, both PRs will be merged at the same time. Note that a test change that contradicts the spec should not be merged before the corresponding spec change. If testing is not practical, please explain why and if appropriate file an issue to follow up later. Add the type:untestable or type:missing-coverage label as appropriate.

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

cssom
cssom-view

Non-substantive contributions

For simple spelling, grammar, or markup fixes unrelated to the substance of a specification, issuing a pull request without a corresponding issue is acceptable.

Further information

Specification source files are in Bikeshed format. The CSSWG wiki has more information on other CSSWG tooling.

See about:csswg for more information on how the CSSWG operates, delegates authority, and makes decisions. Someday maybe we'll also have a useful official website.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!