-
-
Notifications
You must be signed in to change notification settings - Fork 348
/
CONTRIBUTING.html
312 lines (229 loc) · 9.96 KB
/
CONTRIBUTING.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Contributing | Susy Documentation</title>
<link href="assets/img/favicon.ico" rel="shortcut icon">
<link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:400,600|Source+Sans+Pro:400,400i,700,700i" rel="stylesheet">
<link rel="stylesheet" href="assets/webpack/app_styles.min.css" />
</head>
<body>
<svg xmlns="http://www.w3.org/2000/svg" hidden>
<symbol id="icon-logo" viewBox="0 0 16 16">
<path d="M.2 8L0 7.8v-.2C.8 6.9 1.9 5.9 2.7 5l.4.3c-.5.8-1.1 1.6-1.8 2.3 1 1.2 1 1.3 1.7 2.4l-.4.3c-.4-.4-.5-.6-1-1C1 8.6 1.1 8.7.2 8zM13 10c.6-1.1.7-1.1 1.7-2.4-.6-.6-1.3-1.5-1.7-2.3l.3-.3c.8.8 1.8 1.8 2.7 2.6v.2l-.8.7c-.3.3-1.2 1.1-1.8 1.7L13 10z"/><path d="M2.6 13.1H3c.9 0 1.1-.2 1.1-1.4V4.2c0-1.1-.2-1.4-1.1-1.4h-.4v-.6h4.5v.7h-.3c-.9 0-1.1.2-1.1 1.4v3.2h4.6V4.2c0-1.1-.2-1.4-1.1-1.4h-.3v-.6h4.5v.7H13c-.9 0-1.1.2-1.1 1.4v7.5c0 1.1.2 1.4 1.1 1.4h.4v.7H8.9v-.7h.3c.9 0 1.1-.2 1.1-1.4V8.2H5.7v3.5c0 1.1.2 1.4 1.1 1.4h.3v.7H2.6v-.7z"/>
</symbol>
<symbol id="icon-menu" viewBox="0 0 24 28">
<path d="M24 21v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1v-2c0-.547.453-1 1-1h22c.547 0 1 .453 1 1zm0-8v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1v-2c0-.547.453-1 1-1h22c.547 0 1 .453 1 1zm0-8v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1V5c0-.547.453-1 1-1h22c.547 0 1 .453 1 1z"/>
</symbol>
</svg>
<div data-region="app">
<header data-region="banner">
<button data-nav-toggle data-toggle="button" aria-controls="nav" aria-pressed="false" type="button" data-toggle-synced="false">
<svg data-icon="menu" data-icon-size="nav-icon" ><title>menu</title><use xlink:href="#icon-menu" />
</svg>
</button>
<div class="project-title">
<a href="index.html" rel="home" class="project-name">Susy</a>
<span class="project-version">3.0.6</span>
</div>
</header>
<div data-region="container">
<nav data-region="nav" data-toggle="target" id="nav" data-target-id="nav" aria-expanded="false" data-auto-closing="false" data-auto-closing-on-any-click="false">
<form action="search.html">
<input type="text" name="q" placeholder="Search…" required minlength="3">
</form>
<div class="nav-subsection">
<h3 class="nav-home">
<a href="index.html" data-nav="is-not-active">Susy</a>
</h3>
<ul>
<li class="nav-item">
<a href="PHILOSOPHY.html" data-nav="is-not-active">Philosophy</a>
</li>
<li class="nav-item">
<a href="CHANGELOG.html" data-nav="is-not-active">Changelog</a>
</li>
<li class="nav-item">
<a href="CONTRIBUTING.html" data-nav="is-active">Contributing</a>
</li>
</ul>
</div>
<div class="nav-subsection">
<ul>
<li class="nav-subsection">
<h3 class="nav-title">Public Grid API</h3>
<ul>
<li class="nav-item">
<a href="config.html" data-nav="is-not-active">Grid Configuration</a>
</li>
<li class="nav-item">
<a href="api.html" data-nav="is-not-active">Grid Functions</a>
</li>
</ul>
</li>
<li class="nav-subsection">
<h3 class="nav-title">Extras</h3>
<ul>
<li class="nav-item">
<a href="plugin-utils.html" data-nav="is-not-active">Extending Susy</a>
</li>
<li class="nav-item">
<a href="su-math.html" data-nav="is-not-active">Su: Core Math<span class="widont"> </span>Engine</a>
</li>
<li class="nav-item">
<a href="plugin_svg-grid.html" data-nav="is-not-active">Plugin: SVG Grid<span class="widont"> </span>Image</a>
</li>
</ul>
</li>
<li class="nav-subsection">
<h3 class="nav-title">Internal Functions (Private)</h3>
<ul>
<li class="nav-item">
<a href="_normal.html" data-nav="is-not-active">Susy Normalization</a>
</li>
<li class="nav-item">
<a href="_parser.html" data-nav="is-not-active">Susy Syntax<span class="widont"> </span>Parser</a>
</li>
<li class="nav-item">
<a href="_validation.html" data-nav="is-not-active">Su Input<span class="widont"> </span>Validation</a>
</li>
<li class="nav-item">
<a href="_version.html" data-nav="is-not-active">Versioning</a>
</li>
</ul>
</li></ul>
</div>
<div class="nav-subsection">
<h3 class="nav-title">
External Links
</h3>
<ul>
<li class="nav-item">
<a href="http://oddbird.net/susy/" data-nav="is-not-active">Susy Website</a>
</li>
<li class="nav-item">
<a href="http://twitter.com/sasssusy/" data-nav="is-not-active">Twitter @SassSusy</a>
</li>
<li class="nav-item">
<a href="http://oddbird.net/2017/06/28/susy3" data-nav="is-not-active">Intro to<span class="widont"> </span>Susy3</a>
</li>
<li class="nav-item">
<a href="http://susy.readthedocs.io" data-nav="is-not-active">Susy2 Documentation</a>
</li>
<li class="nav-item">
<a href="http://oddbird.net/" data-nav="is-not-active">OddBird</a>
</li>
</ul>
</div>
<aside class="footer-credit">
<a href="http://oddbird.net/herman/" class="footer-icon">
<svg data-icon="logo" data-icon-size="footer-logo" ><use xlink:href="#icon-logo" />
</svg>
</a>
<span>
Documented with
<a href="http://oddbird.net/herman/" class="footer-link">
Herman
</a>
</span>
<span>
by
<a href="http://oddbird.net/" class="footer-link">
OddBird
</a>
</span>
</aside>
</nav>
<main data-region="main">
<nav class="breadcrumb">
<a href="index.html" >Susy</a> »
<strong>Contributing</strong>
</nav>
<div data-page="CONTRIBUTING">
<div class="text-block">
<h1 id="contributing-to-susy">Contributing to Susy</h1>
<p>Susy exists because of your contributions.
Bug reports and feature requests are welcome,
but code is even<span class="widont"> </span>better!</p>
<p>In all cases,
we ask you to follow the
<a href="http://sass-lang.com/community-guidelines">Sass community<span class="widont"> </span>guidelines</a>.</p>
<p>Susy is roughly divided into two layers,
the core grid-math layer is called <strong>Su</strong>,
and is made up of “pure” functions
that expect normalized<span class="widont"> </span>values.</p>
<p>The “Susy” layer provides extra syntax-sugar
to the API –
with parsing, normalization,
and a smaller set of “common” functions
that call on the core math as<span class="widont"> </span>necessary.</p>
<h2 id="development">Development</h2>
<p>Set up your environment
with the appropriate development<span class="widont"> </span>dependencies:</p>
<pre><code>yarn
</code></pre>
<p>As you work…</p>
<ul>
<li>Add or update any appropriate unit tests
in the <code>test</code> directory,
and make sure all tests are passing with <code>npm test</code></li>
<li>Add your changes to the <a href="CHANGELOG.md">changelog</a></li>
<li>Update or add inline documentation
using <a href="http://sassdoc.com/">SassDoc</a> as appropriate,
and compile the docs with <code>npm run sassdoc</code></li>
</ul>
<p><strong>Note:</strong>
The primary API functions
(<code>susy-span</code>, <code>susy-gutter</code>, <code>susy-slice</code>)
all have unprefixed alias functions:
<code>span</code>, <code>gutter</code>, and <code>slice</code>.
Any changes to arguments or defaults
should be made in both<span class="widont"> </span>locations.</p>
<h2 id="committing">Committing</h2>
<p>Linting, testing, and documentation
should be done before every<span class="widont"> </span>commit:</p>
<pre><code>npm run commit
</code></pre>
<p>They can also be triggered<span class="widont"> </span>individually:</p>
<pre><code># lint
npm run lint
# test with mocha/true, and compile ag-test CSS
npm test
# compile full test output for reference
npm run compile
# compile docs
npm run sassdoc
</code></pre>
<p>Optionally use <code>npm run test-libsass</code> for js-only tests,
or <code>rake test</code> for ruby-only<span class="widont"> </span>environments.</p>
<p>Once you’ve fixed any final errors or typos,
commit your changes, and submit a pull<span class="widont"> </span>request!</p>
<h2 id="pull-requests">Pull Requests</h2>
<p>We use the <code>master</code> branch for production-ready code,
and side-branches for everything in-progress
or<span class="widont"> </span>up-for-debate.</p>
<p>When submitting a patch via pull<span class="widont"> </span>request:</p>
<ul>
<li>Write a clear, descriptive commit<span class="widont"> </span>message</li>
<li>Keep it simple: one bug fix or feature per pull<span class="widont"> </span>request</li>
</ul>
<h2 id="release">Release</h2>
<ul>
<li>Update the version number in both
<code>package.json</code> and <code>_version.scss</code>,</li>
<li>Updated the changelog & release<span class="widont"> </span>date</li>
<li><code>npm run commit</code></li>
<li>Release on Github</li>
<li>Publish release to<span class="widont"> </span>NPM</li>
</ul>
</div>
</div>
</main>
</div>
</div>
<script type="text/javascript" src="assets/webpack/runtime.min.js"></script>
<script type="text/javascript" src="assets/webpack/common.min.js"></script>
<script type="text/javascript" src="assets/webpack/app.min.js"></script>
</body>
</html>