Permalink
Mar 29, 2013
Mar 29, 2013
Mar 21, 2016
Mar 29, 2013
Mar 29, 2013
Mar 19, 2016
Mar 29, 2013
Jan 5, 2016
Mar 29, 2013
Mar 29, 2013
Mar 19, 2016
May 2, 2017
Newer
100644
197 lines (144 sloc)
7.28 KB
1
# Contributing to normalize.css
2
3
Please take a moment to review this document in order to make the contribution
4
process easy and effective for everyone involved.
5
6
Following these guidelines helps to communicate that you respect the time of
7
the developers managing and developing this open source project. In return,
8
they should reciprocate that respect in addressing your issue or assessing
9
patches and features.
10
11
12
## Using the issue tracker
13
14
The issue tracker is the preferred channel for [bug reports](#bugs),
15
[features requests](#features) and [submitting pull
16
requests](#pull-requests), but please respect the following restrictions:
17
18
* Please **do not** use the issue tracker for personal support requests.
19
20
* Please **do not** derail or troll issues. Keep the discussion on topic and
21
respect the opinions of others.
22
23
24
## Bug reports
25
26
A bug is a _demonstrable problem_ that is caused by the code in the repository.
27
Good bug reports are extremely helpful - thank you!
28
29
Guidelines for bug reports:
30
31
1. **Use the GitHub issue search** – check if the issue has already been
32
reported.
33
34
2. **Check if the issue has been fixed** – try to reproduce it using the
35
latest `master` branch in the repository.
36
37
3. **Isolate the problem** – create a live example (e.g., on
38
[Codepen](http://codepen.io)) of a [reduced test
39
case](http://css-tricks.com/6263-reduced-test-cases/).
40
41
A good bug report shouldn't leave others needing to chase you up for more
42
information. Please try to be as detailed as possible in your report. What is
43
your environment? What steps will reproduce the issue? What browser(s) and OS
44
experience the problem? What would you expect to be the outcome? All these
45
details will help people to fix any potential bugs.
46
47
Example:
48
49
> Short and descriptive example bug report title
50
>
51
> A summary of the issue and the browser/OS environment in which it occurs. If
52
> suitable, include the steps required to reproduce the bug.
53
>
54
> 1. This is the first step
55
> 2. This is the second step
56
> 3. Further steps, etc.
57
>
58
> `<url>` - a link to the reduced test case
59
>
60
> Any other information you want to share that is relevant to the issue being
61
> reported. This might include the lines of code that you have identified as
62
> causing the bug, and potential solutions (and your opinions on their
63
> merits).
64
65
66
## Feature requests
67
68
Feature requests are welcome. But take a moment to find out whether your idea
69
fits with the scope and aims of the project. It's up to *you* to make a strong
70
case to convince the project's developers of the merits of this feature. Please
71
provide as much detail and context as possible.
72
73
74
## Pull requests
75
76
Good pull requests - patches, improvements, new features - are a fantastic
77
help. They should remain focused in scope and avoid containing unrelated
78
commits.
79
80
**Please ask first** before embarking on any significant work, otherwise you
81
risk spending a lot of time working on something that the project's developers
82
might not want to merge into the project.
83
84
Please adhere to the coding conventions used throughout a project (whitespace,
85
accurate comments, etc.) and any other requirements (such as test coverage).
86
87
Follow this process if you'd like your work considered for inclusion in the
89
90
1. [Fork](https://help.github.com/articles/fork-a-repo/) the project, clone your
91
fork, and configure the remotes:
92
93
```bash
94
# Clone your fork of the repo into the current directory
95
git clone https://github.com/<your-username>/normalize.css
96
# Navigate to the newly cloned directory
97
cd normalize.css
98
# Assign the original repo to a remote called "upstream"
99
git remote add upstream https://github.com/necolas/normalize.css
100
```
101
102
2. If you cloned a while ago, get the latest changes from upstream:
103
104
```bash
105
git checkout master
106
git pull upstream master
107
```
108
109
3. Never work directly on `master`. Create a new topic branch (off the latest
110
version of `master`) to contain your feature, change, or fix:
111
112
```bash
113
git checkout -b <topic-branch-name>
114
```
115
116
4. Commit your changes in logical chunks. Please adhere to these [git commit
117
message conventions](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
118
or your code is unlikely be merged into the main project. Use Git's
119
[interactive rebase](https://help.github.com/articles/interactive-rebase)
120
feature to tidy up your commits before making them public.
121
123
your change in all supported browsers.
124
125
5. Locally rebase the upstream development branch into your topic branch:
126
127
```bash
128
git pull --rebase upstream master
129
```
130
131
6. Push your topic branch up to your fork:
132
133
```bash
134
git push origin <topic-branch-name>
135
```
136
137
10. [Open a Pull Request](https://help.github.com/articles/using-pull-requests/)
138
with a clear title and description.
139
140
**IMPORTANT**: By submitting a patch, you agree to allow the project owner to
141
license your work under the same license as that used by the project.
142
143
### CSS Conventions
144
145
Keep the CSS file as readable as possible by following these guidelines:
146
147
- Comments are short and to the point.
148
- Comments without a number reference the entire rule.
149
- Comments describe the selector when the selector does not make the
150
normalization obvious.
151
- Comments begin with “Correct the...” when they deal with less obvious side
152
effects.
153
- Rules are sorted by cascade, specificity, and then alphabetic order.
154
- Selectors are sorted by specificity and then alphabetic order.
155
- `in browser` applies to all versions.
156
- `in browser v-` applies to all versions up to and including the version.
157
- `in browser v+` applies to all versions after and including the version.
158
- `in browser v-v` applies to all versions including and between the versions.
159
160
161
## Maintainers
162
163
If you have commit access, please follow this process for merging patches and
164
cutting new releases.
165
166
### Accepting patches
167
168
1. Check that a patch is within the scope and philosophy of the project.
169
2. Check that a patch has any necessary tests and a proper, descriptive commit
170
message.
171
3. Test the patch locally.
172
4. Do not use GitHub's merge button. Apply the patch to `master` locally
173
(either via `git am` or by checking the whole branch out). Amend minor
174
problems with the author's original commit if necessary. Then push to GitHub.
175
176
### Releasing a new version
177
178
1. Include all new functional changes in the CHANGELOG.
179
2. Use a dedicated commit to increment the version. The version needs to be
180
added to the CHANGELOG (inc. date), the `package.json`, and `normalize.css`
181
files.
182
3. The commit message must be of `v0.0.0` format.
184
5. Push the changes and tags to GitHub: `git push --tags origin master`
185
6. Checkout the `gh-pages` branch and follow the instructions in the README.
186
187
### Semver strategy
188
189
[Semver](http://semver.org/) is a widely accepted method for deciding how
190
version numbers are incremented in a project. Versions are written as
191
MAJOR.MINOR.PATCH.
192
194
result in a new **major** release. No changes to CSS rules can add
195
functionality in a backwards-compatible manner, therefore no changes are
196
considered **minor**. Others changes with no impact on rendering are considered
197
backwards-compatible and will result in a new **patch** release.