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.

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. 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.
  2. Propose a 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. If you cannot find a suitable language tag; please open a 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:

| 🇫🇷 | 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:

#### 🇩🇪 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!