-
Notifications
You must be signed in to change notification settings - Fork 0
/
contributing.html
283 lines (283 loc) · 23.8 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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=880,maximum-scale=1,minimum-scale=.4">
<meta name="author" content="Barry Cap">
<meta name="description" content="The guidelines for contributing to BarryCap.com.">
<link rel="icon" href="/assets/favicon.ico">
<link rel="icon" href="/assets/favicon.svg">
<link rel="stylesheet" href="styles.css">
<link rel="manifest" href="manifest.json">
<script src="googleanalytics.js"></script>
<script async src="https://www.googletagmanager.com/gtag/js?id=G-GY5Q2KLJ19"></script>
<script async src="script.js"></script>
<title>Barry Cap › Contributing</title>
</head>
<body id="contr-body">
<div class="doc">
<p class="sub-txt img-sub-txt">
<h1><a href="https://barrycap.com">Barry Cap</a> › Contributing</h1>
<hr>
<details>
<summary>Summary</summary>
<ol>
<li><a href="#commits">Commits</a></li>
<li><a href="#versioning">Versioning</a></li>
<li><a href="#languages">Languages</a></li>
<li><a href="#code">Code</a></li>
</ol>
</details>
<p class="em">As a start, I would like to thank everyone who is contributing or who wants to contribute to this repository.</p>
<p class="em">This is a project I made mostly alone, but if anyone wants to collaborate to this site, doing some little typo, design fixes or even art that they want to share, I would be very glad and open for some help and content.</p>
<hr>
<h2 id="commits">Commits</h2>
<p class="em">I am not very strict at naming commits, so I will just exlain some fundamentals.</p>
<hr>
<h3 id="format">Format</h3>
<p class="em">The default format for commit names on this repository is:</p>
<pre class="brks"><c- cya>[verb] [edited]</c-><c- pur>/<c- pin>[old]</c-></c-> <c- ora>(of <c- yel>[nest]</c-> to <c- yel>[value]</c-> in <c- yel>[file]</c->)</c-><c- pur>/by <c- pin>[edited]</c-></c-></pre>
<p class="em">With</p>
<ul>
<li><code><c- cya>[verb]</c-></code> indicating <i>the verb</i>;</li>
<li><code><c- cya>[edited]</c-></code> standing for <i>the name of the file or part of a file edited or added</i>;</li>
<li><code><c- yel>[nest]</c-></code> standing for <i>the element inside which the change is being applied to</i>;</li>
<li><code><c- yel>[value]</c-></code> being <i>the new value of the property that is changed</i>;</li>
<li><code><c- yel>[file]</c-></code> standing for <i>the page or file in which the change is being applied to</i>;</li>
<li><code><c- pin>[old]</c-></code> meaning <i>the old file or part of file before it was edited</i>;</li>
<li><code><c- pur>/</c-></code> indicating <i>another possibility than the group before</i> (if the words after are used, the preceding group is not used).</li>
</ul>
<p class="em">Everything that is inside parenthesis (<code><c- ora>(…)</c-></code>) is not mandatory.</p>
<h4 id="example-1">Example</h4>
<hr>
<p class="em">If the <code><c- red>body</c-></code> text color is set to <code><c- pur>#eee</c-></code> in <code><c- ora>styles.css</c-></code>, the commit name should be:</p>
<pre class="md">Set <c- ora>`color`</c-> of <c- ora>`body`</c-> to <c- ora>`#eee`</c-> in <c- ora>`styles.css`</c-></pre>
<hr>
<h3 id="starting-with-a-verb">Starting with a verb</h3>
<p class="em">Every commit should begin with a verb at the present time, explaining the kind of action that is being executed in the commit.</p>
<ul>
<li>If a new file, class, script etc. is created, the commit name should begin with <code>Add</code> or <code>Create</code>;</li>
<li>If a file is modified, the commit name should begin with <code>Edit</code> or <code>Change</code>;</li>
<li>If information in a file is updated, the commit name should begin with <code>Update</code>;</li>
<li>If an issue, a typo etc. was fixed, the commit name should begin with <code>Fix</code>;</li>
<li>If a style property or an attribute is changed, the commit name should begin with <code>Set</code>;</li>
<li>If something is being deleted, the commit name should begin with <code>Remove</code> or <code>Delete</code>;</li>
<li>If something is being improved, the commit name could begin with <code>Improve</code>;</li>
<li>If a file is being renamed, the commit name could begin with <code>Rename</code>;</li>
<li>If something is being changed for another, the commit name should begin with <code>Replace</code>;</li>
<li>If a file or a part of a file is made shorter or some format errors were fixed, the commit name should begin with <code>Clean</code>;</li>
<li>If a file or a part of a file is shortened or minified, the commit name should begin with <code>Minify</code>.</li>
</ul>
<h4 id="example-2">Examples</h4>
<hr>
<p class="em">If the file <code><c- ora>CONTRIBUTING.md</c-></code> is being added, the commit name could begin with or could to be:</p>
<pre class="md">Add <c- ora>`CONTRIBUTING.md`</c-></pre>
<p class="em">If a property that is linked with the white theme is edited, the commit name would look like:</p>
<pre class="md">Change white theme</pre>
<hr>
<h3 id="followed-by-what-has-been-edited-or-added">Followed by what has been edited or added</h3>
<p class="em">The commit name should include, after the verb, the file name (surrounded by backticks if possible, to be formated <code>like this</code> on <a target="_blank" href="https://github.com">GitHub</a>) or something that has been changed.</p>
<h4 id="example-3">Example</h4>
<hr>
<p class="em">If a script was added in <code><c- ora>script.js</c-></code> to change the random background animation in <a target="_blank" href="https://barrycap.com/random">Random page</a>, the commit name would look like:</p>
<pre class="md">Add script to change background animation in Random page</pre>
<hr>
<h3 id="splitted-if-too-long">Splitted if too long</h3>
<p class="em">To show in a good manner on all displays and viewing modes, the standard limit for the first line of commit names is at 50 (while it is at 72 for any other line).</p>
<h4 id="example-4">Example</h4>
<hr>
<p class="em">The commit name example above is too long (6 characters above the 50 limit), so it has to be splitted in two lines:</p>
<pre class="md">Add script to change background animation
in Random page</pre>
<p class="em">The commit name can be splitted before the announcement of were the modifications are applying to, so generally before the word ‘in’.</p>
<hr>
<h3 id="including-the-number-of-files-modified">Including the number of files modified</h3>
<p class="em">If numerous files that are being edited (e.g. a <code><c- red>meta</c-></code> tag is changed in all HTML files), the commit name should include the number of files modified.</p>
<h4 id="example-5">Example</h4>
<hr>
<p class="em">If the favicon is changed in all 56 HTML pages, the commit name would be:</p>
<pre class="md">Change favicon in all 56 pages</pre>
<hr>
<h3 id="pages-title-capitalized">Pages' title capitalized</h3>
<p class="em">The first letter of a mentioned page needs to be written in capital, generally followed by <code>page</code>.</p>
<h4 id="example-6">Example</h4>
<hr>
<p class="em">If a white theme button is added in Random page, the commit name would be:</p>
<pre class="md">Add white theme button in Random page</pre>
<hr>
<h3 id="fixing-issues">Fixing issues</h3>
<p class="em">If it is certain that an issue will be fixed when merging this commit to the master branch, the commit name can include the issue ID (beginning with <code>#</code>), preceded by <code>Fix</code>, with a white space between the two.</p>
<h4 id="example-7">Example</h4>
<hr>
<p class="em">If the header CSS animation in Intro page is fixed, and if it closed the issue number 78, the commit name could look like:</p>
<pre class="md">Fix header animation in Intro page <u>Fix #78</u></pre>
<hr>
<h3 id="multiple-changes">Multiple changes</h3>
<p class="em">If multiple changes are done in the commit, they have to be separated in different lines.</p>
<h4 id="example-8">Example</h4>
<hr>
<p class="em">If <code><c- ora>CONTRIBUTING.md</c-></code> is added and a typo was fixed in <code><c- ora>README.md</c-></code>, the commit name would be:</p>
<pre class="md">Add <c- ora>`CONTRIBUTING.md`</c->
Fix typo in <c- ora>`README.md`</c-></pre>
<hr>
<h3 id="adding-description">Adding description</h3>
<p class="em">Additional information about what is being done in the commit can be added after a line break, not beginning with a capital letter.</p>
<h4 id="example-9">Example</h4>
<hr>
<p class="em">If <code><c- ora>README.md</c-></code> is updated by adding link to Stack Overflow profile, the commit name could be:</p>
<pre class="md">Update <c- ora>`README.md`</c->
add link to Stack Overflow profile</pre>
<hr>
<h3 id="not-ending-with-a-period">Not ending with a period</h3>
<p class="em">No full stop or any other punctuation character has to be inserted at the end of the commit name.</p>
<hr>
<h3 id="updating-version">Updating version</h3>
<p class="em">Every commit changes something to the site, and this can be seen with the version, that has to be updated with every commit (do not do it in changes that will be applied within a pull request, I will update it myself, in a commit where I have done something else, or in a ‘<code>Update version</code>’ commit). The version indicator can be found in the <code>code</code> block in the <a target="_blank" href="https://barrycap.com/about">About page</a> (<code><c- ora>/about.html</c-></code>).</p>
<hr>
<h2 id="versioning">Versioning</h2>
<p class="em">The version of the site is represented in the below format:</p>
<pre class="brks"><c- cya>[major]</c->.<c- cya>[minor]</c->+<c- cya>[commitNumber]</c-></pre>
<p class="em">The true commit number can be found in the <a target="_blank" href="https://github.com/BarryCap/BarryCap.github.io/graphs/contributors">contributors table</a> of the repository, where all the commits count from every contributor have to be additionned. The commit number can also be found by calculating the number of commits found on the <a target="_blank" href="https://github.com/BarryCap/BarryCap.github.io">repository home page</a> (e.g. 880 at the time this is written) plus 93.</p>
<h4 id="example-10">Example</h4>
<hr>
<p class="em">The version of the site, with the commit introducing <code><c- ora>CONTRIBUTING.md</c-></code>, was:</p>
<pre class="plain">1.6+974</pre>
<p class="em">A new major version is introduced when the website completely changes its appearance. A new minor version is introduced when a big change was made to the website. Contributors will have to demand permission from <a target="_blank" href="https://barrycap.com/about#me">me</a> to update the website to a major or minor version, or their modifications might be refused.</p>
<p class="em">Information about the different versions of the website can be found at <a target="_blank" href="https://barrycap.com/versions">BarryCap.com/versions</a>.</p>
<hr>
<h2 id="languages">Languages</h2>
<p class="em">Most of the website is written in American English. I do not want to see things like ‘colour’, ‘licence’ or ‘realisations’ in the American English version of the website.</p>
<hr>
<h3 id="english-punctuation-rules">English punctuation rules</h3>
<p class="em">I have the habit to be a bit hard with myself on the punctuation marks. There are four points that I would like to explain.</p>
<h4 id="the-dash-en">The dash (<b>—</b>)</h4>
<hr>
<p class="em">The usage of dashes is often confused in many languages, where some people uses only the <a target="_blank" href="https://unicode-table.com/2013/">en dash</a> (–), with or without spaces at its sides, while some are using both for different usage (e.g. en dash for lists, em dash as sentence separator), and there are even other kind of usage… So I will be clear. There is only <b>one type of dash used in English texts</b>, and that is the <a target="_blank" href="https://unicode-table.com/2014/">em dash</a> (—). It has to be used <b>without spaces</b> after nor before.</p>
<h4 id="example-11">Example</h4>
<hr>
<p class="em"><i>The train was about to leave—travelers were jostling for a seat.</i></p>
<h4 id="horizontal-ellipsis-en">Horizontal ellipsis (<b>…</b>)</h4>
<hr>
<p class="em">The usage of <a target="_blank" href="https://unicode-table.com/2026/">horizontal ellipsis</a> is also quite different depending on websites, people etc., some time used as ‘…’ (one character), ‘...’ (three periods) or ‘. . .’ (three periods spaced) The rule on <a target="_blank" href="https://barrycap.com">BarryCap.com</a> is simple: each time horizontal ellipsis have to be used, the Unicode character has to be preferred.</p>
<h4 id="quotation-marks----and">Quotation marks (<b>‘</b>, <b>’</b>, <b>“</b> and <b>”</b>)</h4>
<hr>
<p class="em">Some are using those: ' ( <a target="_blank" href="https://unicode-table.com/0027/">apostrophe</a>, both the same at each end), while others: " ( <a target="_blank" href="https://unicode-table.com/0022/">quotation mark</a>, both the same at each end), some more experimented: “ and ” ( <a target="_blank" href="https://unicode-table.com/201C/">left double quotation mark</a> and <a target="_blank" href="https://unicode-table.com/201D/">right double quotation mark</a>) or ‘ and ’ ( <a target="_blank" href="https://unicode-table.com/2018/">left single quotation mark</a> and <a target="_blank" href="https://unicode-table.com/2019/">right single quotation mark</a>). The rule on <a target="_blank" href="https://barrycap.com">BarryCap.com</a> is to use <b>single quotation marks</b>, different for each end (‘ and ’), and if there is a need for putting quotation marks inside of quotation marks, the characters used will be <b>double quotation marks</b> (“ and ”), also different at each end.</p>
<h4 id="spaces-before-punctuation-marks-en">Spaces before punctuation marks (<b>:</b>, <b>;</b>, <b>?</b>, <b>!</b> and <b>…</b>)</h4>
<hr>
<p class="em">This is generally respected: <b>no space before <a target="_blank" href="https://unicode-table.com/003A/">colons</a>, <a target="_blank" href="https://unicode-table.com/003B/">semicolons</a>, <a target="_blank" href="https://unicode-table.com/0021/">exclamation marks</a>, <a target="_blank" href="https://unicode-table.com/003F/">question marks</a> and <a target="_blank" href="https://unicode-table.com/2026/">horizontal ellipsis</a></b> in English, and most other languages.</p>
<hr>
<h3 id="french-punctuation-rules">French punctuation rules</h3>
<p class="em">French is a language in which punction marks usage often differs from other languages. The thing that is important to French punctuation is the <a target="_blank" href="https://unicode-table.com/00A0/">no-break space</a>, that needs to be placed before or after punctuation marks.</p>
<h4 id="the-dash-fr">The dash (<b>–</b> and <b>—</b>)</h4>
<hr>
<p class="em">The dash used inside sentences will always be the <a target="_blank" href="https://unicode-table.com/2013/">en dash</a> (–), surrounded by regular spaces, unless it is used like parenthesis, framing a part of text in which case a <a target="_blank" href="https://unicode-table.com/00A0/">no-break space</a> (<code><c- pur>&nbsp;</c-></code> in HTML) has to be inserted inside the part of the sentence surrounded by <a target="_blank" href="https://unicode-table.com/2013/">en dashs</a>.</p>
<p class="em">As for dialogues, the dash used will be an <a target="_blank" href="https://unicode-table.com/2014/">em dash</a>, followed by a <a target="_blank" href="https://unicode-table.com/00A0/">no-break space</a>.</p>
<h4 id="example-12">Example</h4>
<hr>
<p class="em">Paragraph:</p>
<br>
<p class="em"><i>Le train s'apprêtait à partir <!--regular space-->– <!--regular space-->les voyageurs se bousculaient pour une place. Il faisait beau <!--regular space-->– c'était le début de l'automne – <!--regular space-->et les feuilles virevoltaient en tous sens.</i></p>
<br>
<p class="em">HTML code (with comments):</p>
<pre class="html"><c- pur>&emsp;</c->Le train s'apprêtait à partir <i><c- gra><!--regular space--></c-></i>– <i><c- gra><!--regular space--></c-></i>les voyageurs se bousculaient pour une place. Il faisait beau <i><c- gra><!--regular space--></c-></i>–<c- pur>&nbsp;</c->c'était le début de l'automne<c- pur>&nbsp;</c->– <i><c- gra><!--regular space--></c-></i>et les feuilles virevoltaient en tous sens.</pre>
<h4 id="horizontal-ellipsis-fr">Horizontal ellipsis (<b>…</b>)</h4>
<hr>
<p class="em">The usage for <a target="_blank" href="https://unicode-table.com/2026/">horizontal ellipsis</a> is the same for French as it is <a target="_blank" href="#horizontal-ellipsis-en">in English</a>: the Unicode character (…) has to be used instead of three periods, and a space must not be inserted before the punctuation mark.</p>
<h4 id="quotation-marks-fr">Quotation marks (<b>«</b> and <b>»</b>)</h4>
<hr>
<p class="em">For french texts, a <a target="_blank" href="https://unicode-table.com/00AB/">left guillemet</a> («, at the beginning) and a <a target="_blank" href="https://unicode-table.com/00BB/">right guillemet</a> (», at the end) need to be used with a <a target="_blank" href="https://unicode-table.com/00A0/">no-break space</a> (<code><c- pur>&nbsp;</c-></code> in HTML) in the inside, instead of common <a target="_blank" href="https://unicode-table.com/0022/">quotation mark</a> (") or any other punctuation mark.</p>
<h4 id="spaces-before-punctuation-marks-fr">Spaces before punctuation marks (<b>:</b>, <b>;</b>, <b>?</b> and <b>!</b>)</h4>
<hr>
<p class="em">The rule is not always respected in French: <b>always add a <a target="_blank" href="https://unicode-table.com/00A0/">no-break space</a> before <a target="_blank" href="https://unicode-table.com/003A/">colons</a>, <a target="_blank" href="https://unicode-table.com/003B/">semicolons</a>, <a target="_blank" href="https://unicode-table.com/0021/">exclamation marks</a> and <a target="_blank" href="https://unicode-table.com/003F/">question marks</a></b>.</p>
<hr>
<h2 id="code">Code</h2>
<p class="em">I have many rules in terms of coding, but I will be quite permissive for any page created by others. However, empty lines in the middle of files are to be avoided in all languages (that ignore empty lines e.g. not Markdown). I will just show some code examples to help perceive the way I code HTML and CSS.</p>
<hr>
<h3 id="html">HTML</h3>
<h4 id="example-13">Example</h4>
<pre class="html"><c- gra><!DOCTYPE html></c->
<<c- red>html</c-> <c- gre>lang</c->=<c- ora>"en"</c->>
<<c- red>head</c->>
<c- gra><i><!--`meta`s, `link`s, `script`s, `title`, and `style` if needed--></i></c->
</<c- red>head</c->>
<<c- red>body</c->><c- gra><i><!--Set `<body class="class-of-body">` for animated backgrounds mostly--></i></c->
<<c- red>div</c->>
<<c- red>a</c-> <c- gre>href</c->=<c- ora>"/"</c->>
<c- gra><i><!--`svg.header-svg`--></i></c->
</<c- red>a</c->>
<<c- red>div</c-> <c- gre>class</c->=<c- ora>"txt"</c->>
<c- gra><i><!--`p.button-container`--></i></c->
<c- gra><i><!--`p.sub-txt`--></i></c->
</<c- red>div</c->>
<c- gra><i><!--images, content etc.--></i></c->
</<c- red>div</c->>
<c- gra><i><!--`div.button-help-container`--></i></c->
<c- gra><i><!--`div.cookie-container`--></i></c->
<c- gra><i><!--`div.footer`--></i></c->
</<c- red>body</c->>
</<c- red>html</c->></pre>
<hr>
<h3 id="css">CSS</h3>
<h4 id="example-14">Example</h4>
<pre class="css"><c- red>@keyframes</c-> <i><c- ora>home</c-></i> { <c- pin>100%</c-> { <i><c- cya>background-position</c-></i>: <c- pur>-32</c-><c- red>px</c-> <c- pur>32</c-><c- red>px</c->; } }
<c- red>body</c-> {
<i><c- cya>background</c-></i>: <c- blu>var</c->(--c0);
<i><c- cya>color</c-></i>: <c- blu>var</c->(--cc);
<i><c- cya>margin</c-></i>: <c- pur>0</c->;
<i><c- cya>cursor</c-></i>: <c- blu>var</c->(--mdef);
<i><c- cya>font-family</c-></i>: <c- blu>var</c->(--ffmb);
<i><c- cya>transition</c-></i>: <c- blu>ease-in</c-> <c- pur>.2</c-><c- red>s</c->;
}
<c- red>div</c-> {
<i><c- cya>padding-top</c-></i>: <c- pur>16</c-><c- red>px</c->;
<i><c- cya>min-height</c-></i>: <c- pur>100</c-><c- red>vh</c->;
}</pre>
<p class="em">The CSS <code><c- red>@keyframes</c-></code> at-rule, as well as all the <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/CSS/At-rule">CSS at-rules</a> need to be minified, at least in the main CSS file (<code><c- ora>styles.css</c-></code>).</p>
<hr>
<h3 id="no-library">Avoid using libraries</h3>
<p class="em">The site must be ‘cleanest’ and ‘lightest’ as possible, <b>not using any HTML, CSS, JavaScript library nor preprocessor for doing things that could be done without one</b>. The following libraries and preprocessors must not take place on this project:
<h4 id="no-library-html">HTML:</h4>
<ul>
<li>Pug;</li>
<li>Halm.</li>
</ul>
<h4 id="no-library-css">CSS:</h4>
<ul>
<li>Slim;</li>
<li>Stylus;</li>
<li>SASS;</li>
<li>SCSS;</li>
<li>Less;</li>
<li>PostCSS.</li>
</ul>
<h4 id="no-library-js">JavaScript:</h4>
<ul>
<li><b>jQuery</b>;</li>
<li>Babel;</li>
<li>CofeeScript;</li>
<li>TypeScript;</li>
<li>LiveScript.</li>
</ul>
<p class="em">And I must have forgotten some of it. If anyone wants to use an open-source library on this website, <a href="mailto:[email protected]">they can demand my agreement</a>.</p>
</p>
</div>
<div class="button-return-container" title="Return">
<a class="button-return" onclick="window.history.go(-1);return false">
<svg viewBox="0 0 40 40">
<path stroke="#fff" stroke-width="8" stroke-linecap="round" d="m4 36 32-32m0 32-32-32"/>
</svg>
</a>
</div>
<footer>
<div class="footer-wide footer-wide-doc">
<p class="footer-table-copyright">© 2022 <a href="/">Barry Cap</a></p>
<nav class="footer-table">
<a class="footer-table-button button" href="/help">Help</a>
<a class="footer-table-button button" href="/contributing">Contribution guidelines</a>
<a class="footer-table-button button" href="/license">License</a>
<a class="footer-table-button button" target="_blank" href="https://github.com/BarryCap/BarryCap.github.io">GitHub</a>
</nav>
</div>
</footer>
</body>
</html>