-
Notifications
You must be signed in to change notification settings - Fork 14
/
contribute.Rmd
212 lines (153 loc) · 7.96 KB
/
contribute.Rmd
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
---
title: "Contribute"
---
## Repository
Contribute at <https://github.com/Bioconductor/bioc_coc_multilingual>.
---
## Version control
### Overview
The _Bioconductor Code of Conduct Policy_ uses version numbering rules
to reflect the different nature of updates to the original version of the
_Bioconductor Code of Conduct Policy_ - maintained by the
_Bioconductor Code of Conduct Committee_ - from translations and fixes to
translations and fixes in other languages.
```{r, echo=FALSE, fig.align='center', out.height='400px'}
knitr::include_graphics("img/contribute-version-control.svg")
```
### Original language (US English)
The original (US English) version of the _Bioconductor Code of Conduct Policy_
increments the **minor** component of the version number at each update.
The **patch** component of the version number should be always kept as `0`.
The **major** component of the version number is reserved for substantial
reworks of the contents and/or structure of the document.
### Translated languages
Translated versions of the _Bioconductor Code of Conduct Policy_ in other
languages are initially marked with the exact same version number as the
original US English that they were translated from.
If fixes are needed to improve the translation of a specific version of the
_Bioconductor Code of Conduct Policy_, the **patch** component of the version
number should be incremented for each fix applied to the translated document.
---
## Files
Each language - from the original US English to every translated language - is
represented by an `.Rmd` file in the top-level directory of this repository.
Those files contains the latest translation of the
_Bioconductor Code of Conduct Policy_ in each language.
Files are named using language tags used to distinguish regional variants of
languages where applicable.
Language tags are currently obtained from [this website][language-tags].
Please open an issue on the repository if you cannot find a language tag
for a proposed translation of the _Bioconductor Code of Conduct Policy_.
Importantly, the `index.Rmd` file lists all the languages currently supported,
as well as the latest version available for each language.
This file must be manually updated at each update of any language.
---
## Processes
### Updates to the original version (US English)
The original version of the _Bioconductor Code of Conduct Policy_ is written in
American English and maintained by the _Bioconductor Code of Conduct Committee_.
To contribute updates to the original version, you may either:
1. Request an update through a [GitHub Issue][github-issue].
2. Propose a [GitHub Pull Request][github-pull-request].
In either case, the _Bioconductor Code of Conduct Committee_ will examine your
proposed changes, and decide whether to implement them in a new version of the
_Bioconductor Code of Conduct Policy_.
In a GitHub issue (option 1), you are expected to describe the nature of the
changes that you would like to propose.
In a pull request (option 2), you are expected to fork the GitHub repository,
write those changes yourself, and open a pull request that will be reviewed
to discuss and make a decision about those changes.
### Update an existing translated version from a newer original (US English) version
When the original (i.e., US English) _Bioconductor Code of Conduct Policy_ is
updated to a new version, this new version is expected to be translated into
every other language at the earliest convenience of volunteer contributors,
replacing earlier version of those translations.
Volunteer contributors are expected to examine the updates in the original
version (e.g., `git diff`), and apply those changes to the translated language.
Remember to update the version number of the translation to the exact version
number of the corresponding US English version, in the translated document as
well as the `index.Rmd` file.
### Add a new translated language from the latest original (US English) version
If you wish to add a new language to list of translations, you will need to
create a new `.Rmd` file for that language, and add a row in the `index.Rmd`
file for that new language.
First, identify a tag for the new language on [this website][language-tags].
If you cannot find a suitable language tag; please open a
[GitHub issue][github-issue] to discuss possible solutions.
Once you have identified a language tag, make a copy of the latest version of
the `en-US.Rmd` file to the new `.Rmd` file for your chosen language.
For instance, if the language tag was `xx-XX`, you could run the following
command in a Terminal:
```
cp en-US.Rmd xx-XX.Rmd
```
Then, open the new file and edit as needed.
Here are a few rules for traceability and convenience:
- Maintain a 1-to-1 mapping between original lines and translated lines;
i.e. do not split or merge lines between original and translated files.
- Maintain the styling and formatting;
e.g., maintain the level of section headers.
- In the title, the language and country names should be written in the
translated language itself, not necessarily English.
Once your translation is completed, remember to update the `index.Rmd`
file as needed.
In particular, new languages will need to be represented by a new line in the
table of translations available.
Here are a few rules, for clarity and convenience:
- The name and country of the language should be written in English,
not the language itself.
- Insert the row for the new language in alphabetical order (latin alphabet);
e.g. [C]hinese -> [E]nglish -> [F]rench
- Indicate the correct version of the code of conduct that you have translated.
- Double-check that the link URL works and the link text matches.
For instance:
```
| `r emo::ji("France")` | French, France | 1.0.1 | [en-US](fr-FR.html) |
```
At this point, you also want to add the new translated language to the
navigation bar, under the `Languages` menu.
To do this, open the `_site.yml` file and edited as needed.
Here are a few rules and reminders:
- Insert a link to the new language in alphabetical order (latin alphabet);
e.g. [C]hinese -> [E]nglish -> [F]rench
- The text of the link should be written in English, not the language itself.
For instance:
```
- text: "French, France"
href: fr-FR.html
```
Finally - having gone through all this -, you are more than entitled to take
credit for your contribution!
Open the `about.Rmd` file and edit as needed, to add yourself as a contributor
to the repository.
Each language should also declare a maintainer. That person will be considered
the primary point of contact for future requests for translations and fixes.
If you worked alone on the translation, then you may consider yourself the
_de facto_ maintainer.
If you worked as a group, please choose one person for the official role.
Here are a few rules and guidelines:
- The name and country of the language should be written in English,
not the language itself.
- One author should be prefixed with `**Maintainer:**`
- Contributors should be associated with a hyperlink that may be used to
identify and contact them.
For instance:
```
#### `r emo::ji("Germany")` German, Germany
- **Maintainer:** [Helena L. Crowell](https://github.com/HelenaLC)
- [Lukas M. Weber](https://github.com/lmweber)
```
One more thing - there is always something -, open the
`.github/ISSUE_TEMPLATE/new-version.md` and add a line for the new language.
That line should contain the markdown syntax for an unticked checkbox (`[ ]`),
the name of the language (in English), and the GitHub handles for the
maintainer, as well as any contributor willing to be notified when a request
for a new translation is made.
```
- [ ] German: @HelenaLC, @lmweber
```
Now you are ready to open that pull request, and watch the new translation
appear on the website as soon as the pull request is approved and built!
[github-issue]: https://github.com/Bioconductor/bioc_coc_multilingual/issues/new/choose
[github-pull-request]: https://github.com/Bioconductor/bioc_coc_multilingual/pulls
[language-tags]: https://www.techonthenet.com/js/language_tags.php