Skip to content

Latest commit

 

History

History
101 lines (76 loc) · 5.15 KB

CONTRIBUTING.md

File metadata and controls

101 lines (76 loc) · 5.15 KB
Raw

Contributing to this database

Pull requests are the most helpful contributions.

We need updates to existing CSS features and to add missing and new features. A feature only needs a name, a description, and a link to its specification, because every feature is "Unrecognized" until we see proof of a stage change from the CSSWG.

Non-CSSWG members can still update CSS features by including citations to public notes that show how the CSSWG is advancing a feature. If you need further clarification, read why we are doing this.

Without further adeu, read about updating a feature or adding-a-new-feature.

Updating a feature

Does one of the CSS features listed here have out-of-date info? Goto css-features and find the feature you want to update. It’s a JSON file, so make changes directly to the JSON and make a pull request.

Adding a new feature

Is an experimental CSS feature not listed here? Add the feature to css-features. You’ll be creating a JSON file, so make additions directly to the JSON and make a pull request.

How the JSON file works

The only fields you’ll see in our JSON file are, in order:

  • title: the name of the feature.
  • description: a brief description of the feature.
  • specification: a link to feature’s specification.
  • stage: the position of the feature within the [staging process]. Stages should be a number, and unrecognized stages should be null.
  • stage: the current stage of the feature; where
    • 0 means Stage 0, i.e. "Aspirational",
    • 1 means Stage 1, i.e. "Experimental",
    • 2 means Stage 2, i.e. "Draft",
    • 3 means Stage 3, i.e. "Adoption",
    • 4 means Stage 4, i.e. "Complete", and
    • null means we don’t know, i.e. "Unrecognized".
  • citations: a list of links realted to the feature and its progress.
  • issues: a link to issue tracking for the feature.
  • polyfills: A list of polyfills used to simulate the feature; which includes
    • name: the shorthand name of the polyfill, and
    • link: the URL to the page or repository for the polyfill.

All contributions must follow the syntax and style of existing JSON files, which; 1. Exist as css-features/${ featureName }.json, where featureName is the kebab-case name representing the title and thematic category of the feature, like hwb-color, matches-pseudo-class, or grid-syntax. 2. Include at least the required fields; name, description, specification, and stage (which is null if you don’t know it).

Did you write the specification you are submitting? It must; 1. Describe what the feature does in as few words as possible. 2. Describe why the feature exists in as few words as possible. 3. Describe how the feature and its parts operate as clearly and completely as possible.

If you’re changing the stage of a feature, be sure to add a citation that proves its new position in the staging process.

Making a Pull Request

For best results, be sure your contributions make sense to everyone else. If you’re unfamiliar with git, consider the following workflow.

  1. To begin, [fork this project], clone your fork, and add our upstream.

    # Clone your fork of the repo into the current directory
git clone https://github.com/<your-user>/css-db
# Navigate to the newly cloned directory
cd css-db
# Assign the original repo to a remote called "upstream"
git remote add upstream https://github.com/jonathantneal/css-db
# Install the tools necessary for development
npm install

  2. Create a branch for your feature or update:

    # Move into a new branch for a feature
git checkout -b feature/thing
    # Or, move into a new branch for a update
git checkout -b update/something

  3. Be sure your code follows our practices.

    # Test current code
npm test

  4. Push your branch up to your fork:

    # Push a feature branch
git push origin feature/thing
    # Or, push a fix branch
git push origin fix/something

Join the CSSWG

Passionate and informed developers should consider joining the CSSWG. Read the instructions for joining the CSSWG. Supposedly this is very difficult to actually accomplish, so pull requests are welcomed to update this section with a beginner-friendly version of these instructions.

Why are we doing this?

The CSSWG doesn’t follow the [TC39 process]. How they operate in theory versus in real life is unclear, and browsers don’t necessarily follow their process anyway, so we have to discern what’s really going on ourselves. If we didn’t, we probably wouldn’t need this repository.