|
2 | 2 | title: "Contributing to the Selenium site & documentation" |
3 | 3 | linkTitle: "Contributing" |
4 | 4 | weight: 2 |
| 5 | +description: >- |
| 6 | + Information on improving documentation and code examples for Selenium |
5 | 7 | aliases: [ |
6 | 8 | "/documentation/en/contributing/", |
7 | 9 | "/documentation/en/front_matter/typographical_conventions/" |
@@ -95,109 +97,7 @@ your changes, run `hugo server` on the site's root directory. |
95 | 97 | % hugo server |
96 | 98 | ``` |
97 | 99 |
|
98 | | -#### Alerts |
99 | | - |
100 | | -Alerts have been added to direct potential contributors to where specific help is needed. |
101 | | - |
102 | | -When code examples are needed, this code has been added to the site: |
103 | | - |
104 | | -{{< highlight html >}} |
105 | | -{{</* alert-code */>}} |
106 | | -{{< /highlight >}} |
107 | | - |
108 | | -Which gets displayed like this: |
109 | | -{{< alert-code >}} |
110 | | - |
111 | | -When additional content is needed, this code has been added to the site |
112 | | -{{< highlight html >}} |
113 | | -{{</* alert-content */>}} |
114 | | -Additional information about what specific content is needed |
115 | | -{{</* /alert-content */>}} |
116 | | -{{< /highlight >}} |
117 | | - |
118 | | -Which gets displayed like this: |
119 | | -{{< alert-content >}} |
120 | | -Additional information about what specific content is needed |
121 | | -{{< /alert-content >}} |
122 | | - |
123 | | -#### Capitalization of titles |
124 | | - |
125 | | -Our documentation uses Title Capitalization for `linkTitle` which should be short |
126 | | -and Sentence capitalization for `title` which can be longer and more descriptive. |
127 | | -For example, a `linkTitle` of _Special Heading_ might have a `title` of |
128 | | -_The importance of a special heading in documentation_ |
129 | | - |
130 | | -#### Line length |
131 | | - |
132 | | -When editing the documentation’s source, |
133 | | -which is written in plain HTML, |
134 | | -limit your line lengths to around 100 characters. |
135 | | - |
136 | | -Some of us take this one step further |
137 | | -and use what is called |
138 | | -[_semantic linefeeds_](//rhodesmill.org/brandon/2012/one-sentence-per-line), |
139 | | -which is a technique whereby the HTML source lines, |
140 | | -which are not read by the public, |
141 | | -are split at ‘natural breaks’ in the prose. |
142 | | -In other words, sentences are split |
143 | | -at natural breaks between clauses. |
144 | | -Instead of fussing with the lines of each paragraph |
145 | | -so that they all end near the right margin, |
146 | | -linefeeds can be added anywhere |
147 | | -that there is a break between ideas. |
148 | | - |
149 | | -This can make diffs very easy to read |
150 | | -when collaborating through git, |
151 | | -but it is not something we enforce contributors to use. |
152 | | - |
153 | | -#### Translations |
154 | | - |
155 | | -The docs are translated into several languages, and translations are based on |
156 | | -the English content. When you are changing a file, **be sure** to make your |
157 | | -changes in all the other translated files as well. This might differ depending |
158 | | -on the change, for example: |
159 | | - |
160 | | -* If you add a code example to the `browser_manipulation.en.md` file, |
161 | | -also add it to `browser_manipulation.ja.md`, `browser_manipulation.pt-br.md`, |
162 | | -`browser_manipulation.zh-cn.md`, and all other translated files. |
163 | | -* If you find a translation that can be improved, only change the translated |
164 | | -file. |
165 | | -* If you are adding a new language translation, add the new files with the |
166 | | -appropriate suffix. There is no need to have everything translated to submit a |
167 | | -PR, it can be done iteratively. Don't forget to check some needed configuration |
168 | | -values in the `config.toml` file. |
169 | | -* If you make text changes in the English version, replace the same section in |
170 | | -the translated files with your change (yes, in English), and add the following |
171 | | -notice at the top of the file. |
172 | | - |
173 | | - |
174 | | -``` |
175 | | -{{%/* pageinfo color="warning" */%}} |
176 | | -<p class="lead"> |
177 | | - <i class="fas fa-language display-4"></i> |
178 | | - Page being translated from |
179 | | - English to {LANGUAGE}. Do you speak {LANGUAGE}? Help us to translate |
180 | | - it by sending us pull requests! |
181 | | -</p> |
182 | | -{{%/* /pageinfo */%}} |
183 | | -``` |
184 | | - |
185 | | -#### Code Tabs |
186 | | - |
187 | | -When adding code examples, you want to use tab panes as follows. |
188 | | -You do not need to provide examples in all languages, |
189 | | -but add placeholders like this for any language you do not implement: |
190 | | - |
191 | | -{{< highlight html >}} |
192 | | -{{</* tabpane langEqualsHeader=true */>}} |
193 | | -{{</* tab header="Java" */>}}Java code not implemented, please make a Pull Request if you can add this code{{</* /tab */>}} |
194 | | -{{</* tab header="Python" */>}}Python code not implemented, please make a Pull Request if you can add this code{{</* /tab */>}} |
195 | | -{{</* tab header="CSharp" */>}}C# code not implemented, please make a Pull Request if you can add this code{{</* /tab */>}} |
196 | | -{{</* tab header="Ruby" */>}}Ruby code not implemented, please make a Pull Request if you can add this code{{</* /tab */>}} |
197 | | -{{</* tab header="JavaScript" */>}}JS code not implemented, please make a Pull Request if you can add this code{{</* /tab */>}} |
198 | | -{{</* tab header="Kotlin" */>}}Kotlin code not implemented, please make a Pull Request if you can add this code{{</* /tab */>}} |
199 | | -{{</* /tabpane */>}} |
200 | | -{{< /highlight >}} |
| 100 | +See [Style Guide]({{< ref "style.md" >}}) for more information on our conventions for contribution |
201 | 101 |
|
202 | 102 | ### Step 4: Commit |
203 | 103 |
|
|
0 commit comments