Skip to content

Commit 19a0c4e

Browse files
jonathantnealjonathantneal
committed
Update documentation
1 parent 3331c9a commit 19a0c4e

File tree

2 files changed

+108
-87
lines changed

2 files changed

+108
-87
lines changed

‎CONTRIBUTING.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
## Contributing to this database
2+
3+
Pull requests are the most helpful contributions.
4+
5+
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](#join-the-csswg).
6+
7+
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](#why-are-we-doing-this).
8+
9+
Without further adeu, read about [updating a feature](#updating-a-feature) or [adding-a-new-feature](#adding-a-new-feature).
10+
11+
#### Updating a feature
12+
13+
Does one of the CSS features listed here have out-of-date info? Goto [css-features](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](#making-a-pull-request).
14+
15+
##### Adding a new feature
16+
17+
Is an experimental CSS feature not listed here? Add the feature to [css-features](css-features). You’ll be creating a JSON file, so make additions directly to the JSON and [make a pull request](#making-a-pull-request).
18+
19+
#### How the JSON file works
20+
21+
The only fields you’ll see in our JSON file are, in order:
22+
23+
- `title`: the name of the feature.
24+
- `description`: a brief description of the feature.
25+
- `specification`: a link to feature’s specification.
26+
- `stage`: the position of the feature within the [staging process]. Stages should be a number, and unrecognized stages should be `null`.
27+
- `stage`: the current [stage](README.md#staging-process) of the feature; where
28+
+ `0` means Stage 0, i.e. "*Aspirational*",
29+
+ `1` means Stage 1, i.e. "*Experimental*",
30+
+ `2` means Stage 2, i.e. "*Draft*",
31+
+ `3` means Stage 3, i.e. "*Adoption*",
32+
+ `4` means Stage 4, i.e. "*Complete*", and
33+
+ `null` means we don’t know, i.e. "*Unrecognized*".
34+
- `citations`: a list of links realted to the feature and its progress.
35+
- `issues`: a link to issue tracking for the feature.
36+
- `polyfills`: A list of polyfills used to simulate the feature; which includes
37+
+ `name`: the shorthand name of the polyfill, and
38+
+ `link`: the URL to the page or repository for the polyfill.
39+
40+
All contributions must follow the syntax and style of existing JSON files, which;
41+
1. Exist as `css-features/${ featureName }.json`, where `featureName` is the [kebab-case](http://wiki.c2.com/?KebabCase) name representing the title and thematic category of the feature, like `hwb-color`, `matches-pseudo-class`, or `grid-syntax`.
42+
2. Include at least the required fields; **name**, **description**, **specification**, and **stage** (which is `null` if you don’t know it).
43+
44+
Did you write the specification you are submitting? It must;
45+
1. Describe what the feature does in as few words as possible.
46+
2. Describe why the feature exists in as few words as possible.
47+
3. Describe how the feature and its parts operate as clearly and completely as possible.
48+
49+
If you’re changing the **stage** of a feature, be sure to add a **citation** that proves its new position in the [staging process](README.md#staging-process).
50+
51+
### Making a Pull Request
52+
53+
For best results, be sure your contributions make sense to everyone else. If you’re unfamiliar with git, consider the following workflow.
54+
55+
1. To begin, [fork this project], clone your fork, and add our upstream.
56+
```bash
57+
# Clone your fork of the repo into the current directory
58+
git clone https://github.com/<your-user>/css-db
59+
# Navigate to the newly cloned directory
60+
cd css-db
61+
# Assign the original repo to a remote called "upstream"
62+
git remote add upstream https://github.com/jonathantneal/css-db
63+
# Install the tools necessary for development
64+
npm install
65+
```
66+
67+
2. Create a branch for your feature or update:
68+
```bash
69+
# Move into a new branch for a feature
70+
git checkout -b feature/thing
71+
```
72+
```bash
73+
# Or, move into a new branch for a update
74+
git checkout -b update/something
75+
```
76+
77+
3. Be sure your code follows our practices.
78+
```bash
79+
# Test current code
80+
npm test
81+
```
82+
83+
4. Push your branch up to your fork:
84+
```bash
85+
# Push a feature branch
86+
git push origin feature/thing
87+
```
88+
```bash
89+
# Or, push a fix branch
90+
git push origin fix/something
91+
```
92+
93+
---
94+
95+
### Join the CSSWG
96+
97+
Passionate and informed developers should consider joining the CSSWG. Read the [instructions for joining the CSSWG](https://www.w3.org/2004/01/pp-impl/32061/instructions). 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.
98+
99+
### Why are we doing this?
100+
101+
The CSSWG doesn’t follow the [TC39 process]. How they operate [in theory](https://www.w3.org/Style/CSS/specs.en.html) versus [in real life](http://fantasai.inkedblade.net/weblog/2011/inside-csswg/) is unclear, and browsers [don’t necessarily follow their process anyway](https://www.chromestatus.com/feature/5753701012602880), so we have to discern what’s really going on ourselves. If we didn’t, we probably wouldn’t need this repository.

‎README.md

Lines changed: 7 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
1-
# CSS Database [<img src="https://rawgit.com/jonathantneal/media-expressions-spec/gh-pages/css-logo.svg" alt="CSS Logo" width="90" height="90" align="right">][CSS Database]
1+
# CSS Features Database [<img src="https://rawgit.com/jonathantneal/media-expressions-spec/gh-pages/css-logo.svg" alt="CSS Logo" width="90" height="90" align="right">][CSS Database]
22

33
[![Build Status][cli-img]][cli-url]
44
[![Licensing][lic-img]][lic-url]
55
[![Changelog][log-img]][log-url]
66

77
[CSS Database] is a comprehensive list of CSS features and their positions in the process of becoming implemented web standards. These positions reflect the [TC39 process].
88

9+
Did you come here to update the status of a CSS feature or add a new one? Quick, read our [CONTRIBUTING.md].
10+
911
## Staging Process
1012

1113
This staging process reflects the real-life stability of new CSS features.
@@ -34,120 +36,38 @@ A CSS specification formally endorsed by the [CSSWG] and requiring implementatio
3436

3537
> “This idea is becoming part of the web.”
3638
37-
A CSS specification formally endorsed by the [CSSWG] and being implemented by [recognized browser vendors], possibly behind a flag. It should be considered stable and subject to little change.
39+
A CSS specification formally endorsed by the [CSSWG] and being implemented by [recognized browser vendors](#recognized-browser-vendors), possibly behind a flag. It should be considered stable and subject to little change.
3840

3941
#### Stage 4: Complete
4042

4143
> “This idea is part of the web.”
4244
43-
A CSS specification formally endorsed by the [CSSWG] and implemented by all [recognized browser vendors].
45+
A CSS specification formally endorsed by the [CSSWG] and implemented by all [recognized browser vendors](#recognized-browser-vendors).
4446

4547
#### No Stage: Unrecognized
4648

4749
> “I have no idea what I’m doing.”
4850
4951
This is any specification that has not yet been presented to the [CSSWG], or that has been formally rejected or deprecated by the [CSSWG].
5052

51-
## Contributing
52-
53-
### Join the CSSWG
54-
55-
Passionate and informed developers should consider joining the CSSWG. Read the [instructions for joining the CSSWG]. Pull requests are welcomed to update this section with a beginner-friendly version of those instructions.
56-
57-
### Update this database
58-
59-
Pull requests are some of the greatest contributions, so be sure they are focused in scope and avoid unrelated commits.
60-
61-
- All contributions must follow the syntax and style of existing JSON files, which;
62-
1. Exist as `features/${ feature }.json`, where `feature` is a thematic, [kebab-case] label representing the title and category of the feature.
63-
2. Include all the [required fields].
64-
65-
- New features include a link to a specification, which;
66-
1. Describes what the feature does in as few words as possible.
67-
2. Describes why the feature exists in as few words as possible.
68-
3. Describes how the feature and its parts operate as clearly and completely as possible.
69-
70-
- Changing features include a relevant citation proving its new position in the [staging process].
71-
72-
For best results, be sure your contributions make sense to everyone else. If you’re unfamiliar with git, consider the following workflow.
73-
74-
1. To begin, [fork this project], clone your fork, and add our upstream.
75-
```bash
76-
# Clone your fork of the repo into the current directory
77-
git clone https://github.com/<your-user>/${ id }
78-
# Navigate to the newly cloned directory
79-
cd ${ id }
80-
# Assign the original repo to a remote called "upstream"
81-
git remote add upstream https://github.com/${ user }/${ id }
82-
# Install the tools necessary for development
83-
npm install
84-
```
85-
86-
2. Create a branch for your feature or update:
87-
```bash
88-
# Move into a new branch for a feature
89-
git checkout -b feature/thing
90-
```
91-
```bash
92-
# Or, move into a new branch for a update
93-
git checkout -b update/something
94-
```
95-
96-
3. Be sure your code follows our practices.
97-
```bash
98-
# Test current code
99-
npm test
100-
```
101-
102-
4. Push your branch up to your fork:
103-
```bash
104-
# Push a feature branch
105-
git push origin feature/thing
106-
```
107-
```bash
108-
# Or, push a fix branch
109-
git push origin fix/something
110-
```
111-
11253
---
11354

11455
## Terminology
11556

116-
### Required Fields
117-
118-
Required fields within a JSON file are, in order:
119-
120-
- **`title`**: a unique name for the feature.
121-
- **`description`**: a brief description of the feature.
122-
- **`specification`**: a link to the latest draft of the specification.
123-
- **`stage`**: the position of the feature within the [staging process]. Stages should be a number, and unrecognized stages should be `null`.
124-
- **`citations`**: an array of links related to the feature or its progress.
125-
126-
### Additional Fields
127-
128-
Additional fields within a JSON file may be, in order:
129-
130-
- **`issues`**: a link to issue tracking for the feature.
131-
- **`polyfills`**: an array of links to polyfills for the feature. Each link contains a `name` and `link` field, in that order.
132-
13357
### Recognized Browser Vendors
13458

13559
Recognized browser vendors include, in alphabetical order; Apple, Google, Microsoft, Mozilla, and Opera.
13660

137-
### Champion
61+
### What is a champion?
13862

13963
A champion is the person responsible for advocating a new CSS feature to completion, performing the legwork necessary to ensure the concerns of interested [CSSWG] members are identified and incorporated into the proposal.
14064

14165
[Champion]: #champion
14266
[CSSWG]: https://wiki.csswg.org/spec
14367
[CSS Database]: https://github.com/jonathantneal/css-db
68+
[CONTRIBUTING.md]: CONTRIBUTING.md
14469
[fork this project]: fork
14570
[inside view of the CSSWG]: http://fantasai.inkedblade.net/weblog/2011/inside-csswg/process
146-
[instructions for joining the CSSWG]: https://www.w3.org/2004/01/pp-impl/32061/instructions
147-
[kebab-case]: http://wiki.c2.com/?KebabCase
148-
[recognized browser vendors]: #recognized-browser-vendors
149-
[required fields]: #required-fields
150-
[staging process]: #staging-process
15171
[TC39 process]: https://thefeedbackloop.xyz/tc39-a-process-sketch-stages-0-and-1/
15272

15373
[npm-url]: https://www.npmjs.com/package/css-db

0 commit comments

Comments
 (0)