Skip to content

Latest commit

 

History

History
226 lines (179 loc) · 9.82 KB

CONTRIBUTING.md

File metadata and controls

226 lines (179 loc) · 9.82 KB
Raw

Contributing

We welcome contributions! In short:

  • If you believe that a spec should be added to the list, please use the "New spec" issue template.
  • If you would like to suggest that a spec already present in the list be modified or removed, consider submitting a pull request, taking the considerations below into account. Alternatively, feel free to raise an issue.

On top of contributions to the list of specs, we also welcome contributions to the code or suggestions to add new features!

Please note the open source data and code license for this project.

Table of Contents

How to add a spec

Before suggesting a new spec, check the Spec selection criteria.

The project uses a semi-automated process to manage spec additions to the list. Please do not create a pull request! Instead, use the "New spec" issue template to suggest a new spec.

On top of the spec URL, you may need to set additional properties, see Spec entries in specs.json for details on possible properties.

How to modify/remove a spec

If you believe that a spec should modified, or removed from the list, consider submitting a pull request, taking the considerations below into account. Alternatively, feel free to raise an issue.

Pre-requisites

To prepare a pull request, please:

The actual list is in specs.json

In practice, the index.json file is automatically generated by processing the specs.json file, which thus contains the actual list. In other words, all proposed changes must be made against the specs.json file, do not edit the index.json file directly.

Spec entries in specs.json

The specs.json file is essentially a sorted (A-Z order) list of URLs. In most cases, a spec entry is merely a versioned URL (see url in README) at the right position in the list.

Some spec entries need to go beyond a simple URL because the spec does not follow usual rules and the code cannot compute the right information as a result. A spec entry in the list may also be an object with the following properties:

  • url: same as the url property in index.json.
  • shortname: same as the shortname property in index.json. When the forkOf property is also set, note that the actual shortname in the final list will be prefixed by the shortname of the base spec (as in: ${forkOf}-fork-${shortname}).
  • forkOf: same as the forkOf property in index.json. No need to set seriesComposition to "fork" when this property is set, the build logic will take care of that automatically.
  • series: same as the series property in index.json, but note the currentSpecification property will be ignored.
  • seriesVersion: same as the seriesVersion property in index.json.
  • seriesComposition: same as the seriesComposition property in index.json. The property must only be set for delta spec, since full is the default and fork specs are identified through the forkOf property in specs.json.
  • organization: same as the organization property in index.json to specify the name of the organization that owns the spec.
  • groups: same as the groups property in index.json to specify the list of groups that develop or developed the spec.
  • nightly: same as the nightly property in index.json. The property must only be set when:
    • The URL of the nightly spec returned by external sources would be wrong and when it cannot be fixed at the source.
    • The code cannot compute the right sourcePath because the source file of the nightly spec does not follow a common pattern.
    • One or more alternate URLs, used in external sources, need to be recorded in an alternateUrls property (note the w3c.github.io URL of CSS drafts is automatically added as an alternate URL, no need to specify it in specs.json)
  • tests: same as the tests property in index.json. The property must only be set when:
    • The test suite of the specification is not in a well-known repository.
    • The code cannot determine the correct list of testPaths and/or excludePaths.
  • shortTitle: same as the shortTitle property in index.json. The property must only be set when the short title computed automatically is not the expected one.
  • forceCurrent: a boolean flag to tell the code that the spec should be seen as the current spec in the series. The property must only be set when value is true.
  • multipage: a flag to identify the spec as a multipage spec. This instructs the code to extract the list of pages from the index page and fill out the release.pages and nightly.pages properties in the list. Possible values for the flag: "nightly" to signal that the nightly version is multipage, "release" to signal that the release version if multipage, or "all" to signal that both the nightly and release versions are multipage.
  • categories: an array that is treated as incremental update to adjust the list of categories that the spec belongs to. Values may be one of "reset" to start from an empty list, "+browser" to add "browser" to the list, and "-browser" to remove "browser" from the list.
  • standing: the spec's standing if default rule would not set it properly, see standing.
  • obsoletedBy: a list of shortnames to identify specs that replace or otherwise obsolete a discontinued spec, see obsoletedBy.
  • formerNames: a list of shortnames that were used to identify the spec, see formerNames.

You should only set these properties when they are required to generate the right info. For instance, some of these properties are needed for Media Queries Level 3, because the spec uses an old shortname format, leading to the following definition in specs.json, to specify the version of the spec and link it to other specs in the same series:

{
  "url": "https://www.w3.org/TR/css3-mediaqueries/",
  "seriesVersion": "3",
  "series": {
    "shortname": "mediaqueries"
  }
}

The linter will enforce typical constraints on the properties, such as making sure that there is only one spec flagged as current in a series. It will also complain when a property is set whereas it does not seem needed.

Compact form preferred

Some of the above properties can be specified with a keyword next to the URL of the spec, allowing to keep using a string instead of an object in most cases:

  • A delta spec can be defined by appending a delta keyword to the URL, instead of through the seriesComposition.
  • The forceCurrent flag can be set by appending a current keyword to the URL
  • The multipage flag can be set by appending a multipage keyword to the URL

For instance, to flag the CSS Fragmentation Module Level 3 as the current spec in the series, the CSS Grid Layout Module Level 2 as a delta spec, and the SVG2 spec as a multipage spec, use the following compact definitions:

[
  "https://www.w3.org/TR/css-break-3/ current",
  "https://www.w3.org/TR/css-grid-2/ delta",
  "https://www.w3.org/TR/SVG2/ multipage"
]

This compact form is preferred to keep the list (somewhat) human-readable. The linter automatically convert objects to the more compact string format whenever possible.

No index.json in the pull request

The index.json file will be automatically generated once your pull request has been merged. Please do not include it in your pull request. You may still wish to re-generate the file (see the Check before push section below) to check that the generated info will be correct, but please don't commit these changes.

Lint before push

Before you push your changes and submit a pull request, please run the linter to identify potential linting issues:

npm run lint

If the linter reports errors that can be fixed (e.g. wrong spec order, or more compact form needed), run the following command to overwrite your local specs.json file with the linted version.

npm run lint-fix

Note: The linter cannot fix broken JSON and/or incorrect properties. Please fix these errors manually and run the linter again.

Check before push

Before you push your changes and submit a pull request, you may also want to check that the changes will produce the right info. You may re-generate the file but generation typically takes several minutes. To only generate the entries that match the specs that you changed in specs.json, you may use the diff tool.