jamulussoftware · ann0see · Dec 27, 2020 · Dec 7, 2020 · Dec 7, 2020 · Dec 7, 2020
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,5 +1,41 @@
-# Contribute
+# Contribute to the documentation
+We really appreciate your support!
 
-Thanks for your support!
-Please open an issue on github. More to come soon...
-~~Please open a pull request on GitHub!~~
+Please note that discussions should be kept in English. If you don't speak English fluently you can use a reasonably good online translator (e.g. [DeepL](https://www.deepl.com), [Reverso](https://www.reverso.net/text_translation.aspx), ...) which might be able to translate your language to English.
+
+Please have a look at the [issues page on GitHub](https://github.com/jamulussoftware/jamuluswebsite/issues) and check if anybody has raised an issue with the same topic.
+
+If this is the case, please subscribe to the issue and explain your proposal.
+
+If that's not the case, please open a [new issue](https://github.com/jamulussoftware/jamuluswebsite/issues/new/choose), select which type of issue it is and describe your issue.
+
+If you want to open a Pull Request (after having described and discussed your proposal), keep in mind that your changes (if they are not just typos) might have to wait until everything is translated. We will bundle them (if everything is all right) with any other changes and upload all of them as a combined Pull Request to jamulus.io.
+
+Pull requests/issues for the website should have a title which looks like this:
+
+`[Tag (like Bug, Translation, etc.)][language code (e.g. en)] {short description of your changes}`
+
+## Branches, Translation and development process
+
+We currently use *multiple branches* to ensure that translators know what to translate.
+
+After having discussed and agreed on changes you want to be integrated to jamulus.io, you should ask yourself some questions:
+
+## 0. Is your content in a language that already exists on the site?
+If not: This will be discussed this later (since you introduce a new language).
+If so look here:
+### 1. Be clear if your change needs translation
+**No:** A fix which doesn't need to be translated (e.g. typo) --> Open a Pull Request to `release`. It will go live a few minutes after the PR is merged
+**Yes:** A fix which needs to be translated (e.g. if you want to make a sentence or paragraph clearer) --> Commit to `changes` since others will need to translate it. It will be part of the next release.
+
+### 2. Be clear if a translation update is going on
+You can see this if we ping the translators in a PR from changes to translate.
+
+**If yes:** only translate the changes of the Pull Request from changes to translation. If you find issues, start with 1
+**If no:** no need to care about the translate branch
+
+## Adding a new language
+
+1. Open an issue with the title [Translate] `yourLanguage` and say that you want to translate the homepage into your language.
+2. If you start your new translation, follow the instructions to add a new language in the /README.md file on the changes branch.
+3. Finally, open a PR to `translate`
diff --git a/README.md b/README.md
@@ -1,44 +1,44 @@
 # Jamulus Website
 
-This is the home of the [Jamulus website](https://jamulus.io) and wiki.
-
-## Tech
-
-Built with Jekyll and Fox-CSS
-
-## Contribute and translation
-
-Do you want to contribute to the Jamulus Wiki/Website? Please open an issue since we're currently discussing how to fasciliate contribution. ~~See the [CONTRIBUTING.md](CONTRIBUTING.md) file and the [contributing wiki entry](https://jamulus.io/wiki/Contribution).~~
+This is the home of the [Jamulus website](https://jamulus.io). The goal of this page is to explain what Jamulus is and how to use it.
 
 ## Adding pictures
 Unfortunately GitHub doesn't enable picture upload on the normal md editor. Therefore you can attempt to open an issue, upload your image, copy the link to the page you want to integrate it into and then don't submit the issue. See this answer on stack overflow: https://stackoverflow.com/a/26601810
 
-## Translating
+## Contribute a translation
 
-Translations are handled by the [Polyglot jekyll Plug-in](https://github.com/untra/polyglot).
+**Before translating, please have a look at the [CONTRIBUTING.md](CONTRIBUTING.md) file to get familiar with our translation process. Afterwards, check if there's already a discussion thread for your language here: https://github.com/jamulussoftware/jamuluswebsite/discussions and participate in it**
+
+Translations are handled by the [Polyglot Jekyll Plug-in](https://github.com/untra/polyglot).
 If you want to translate a file, you must first know where it is located on this repo:
 
--   General translations especially for the wiki can be found in \_includes/wiki/yourlanguagecode folder. These files **must** be translated in order not to break the site.
--   The homepage is located in the repo root and named [langcode]-index.html
+-   General translations (especially for the wiki) can be found in \_includes/wiki/yourlanguagecode folder. These files **must** be translated in order not to break the site.
+-   The homepage (https://jamulus.io/) is located in the repo root and named 1-[langcode]-index.html
 -   The wiki content can be found in the wiki/ folder. Make sure to read the README.md file in the wiki/ folder.
 -  The navigation and general translations can be found in the \_data/yourlanguagecode folder
 
 
-To translate a file, please duplicate it and change the `lang:` attribute to the language you want to translate it to. If you want to translate an English page to German, you need to change the `lang: "en"` attribute to `lang: "de"`. This attribute can be found at the top of the file in the front matter (right at the top in between the `---`). Do not change the permalink attribute. It links pages with the same content but different languages and enables polyglot to know which page to change to if you change the language via the language picker.
+To translate a file, please duplicate it and change the `lang:` attribute to the language you want to translate it to. If you want to translate an English page to German, you need to change the `lang: "en"` attribute to `lang: "de"`. This attribute can be found at the top of the file in the front matter (right at the top in between the `---`). Do not change the permalink attribute (It internally links pages with the same content but different languages and enables polyglot to know which page to change to if you change the language via the language picker.)
 
 ### Adding a new language
 
 If you want to add a new language, you must follow the instructions on the polyglot site and add the folders/files.
 - Make sure to add your language to the \_config.yml file (in the languages array.)
 - At least, the main includes for the wiki (see \_includes/wiki/) have to be translated.
-- The navigation and general site wide strings (see the \_data/ folder) and the homepage (see the 1-index.html file in the root of this repo) should be translated.
+- The navigation and general site-wide strings (see the \_data/ folder) and the homepage (see the 1-index.html file in the root of this repo) should be translated.
 
 Have a look at the README.md files in these folders.
 
+## Tech
+
+This site is built with Jekyll and Fox-CSS.
+
 ## Contribute to the design/site structure
+Please open an issue and see the [CONTRIBUTING.md](CONTRIBUTING.md) file.
 
-Since this page uses Jekyll, please have a look at the [jekyll documentation](https://jekyllrb.com/docs/).
-This project uses the fox css framework. See the [FOX-CSS documentation](http://www.fox-css.com/documents/).
+### A few tips/links
+Since this page uses Jekyll, please have a look at the [Jekyll documentation](https://jekyllrb.com/docs/).
+This project uses the FOX-CSS framework. See the [FOX-CSS documentation](http://www.fox-css.com/documents/).
 CSS files can be found in the assets/css folder.
 The \_layouts folder holds the main layouts for the page.
 More information can be found at the README.md files in (almost) every folder.
diff --git a/wiki/en/en-Contribution.md b/wiki/en/en-Contribution.md
@@ -8,18 +8,31 @@ permalink: "/wiki/Contribution"
 # Contributing to the Jamulus Project
 
 ## Jamulus Software
-* If you want to contribute code, post your idea on [the developer forum](https://sourceforge.net/p/llcon/discussion/developerforum/) first so that it can be discussed before making a pull request (be sure to read main dev's [Volker's manifesto for contributions](https://github.com/corrados/jamulus/issues/596))
+
+If you want to contribute code or have a feature request, [open an issue on GitHub](https://github.com/corrados/jamulus/issues/) (preferred) or [post your idea on the developer forum](https://sourceforge.net/p/llcon/discussion/developerforum/) if you don't have a GitHub account. This allows us to discuss the changes before e.g. making a pull request (be sure to read main dev's [Volker's manifesto for contributions on GitHub](https://github.com/corrados/jamulus/issues/596) and the [CONTRIBUTING file](https://github.com/corrados/jamulus/blob/master/CONTRIBUTING.md))
 
 See the [Jamulus GitHub repo](https://github.com/corrados/jamulus) for further information.
 
 ## Jamulus Website
 
-* If you find a mistake, typo or something out of date (in any language) on the website, you can [raise it as an issue here](https://github.com/jamulussoftware/jamuluswebsite/issues).
+* If you find a mistake, typo or something out of date (in any language) on the website, you can [open an issue on GitHub](https://github.com/jamulussoftware/jamuluswebsite/issues) or, if you don't have a GitHub account on [the relevant discussion forum](https://sourceforge.net/p/llcon/discussion/) on SourceForge.
 
 * If you think some documentation or information is missing or can be improved, post about that on [the relevant discussion forum](https://sourceforge.net/p/llcon/discussion/) so that it can be discussed first.
 
-Pull requests for the website should look like this:
+Have a look at the [CONTRIBUTING file](https://github.com/jamulussoftware/jamuluswebsite/blob/changes/CONTRIBUTING.md) for the website and the [Website GitHub repo](https://github.com/jamulussoftware/jamuluswebsite) for further information.
+
+### I don't know GitHub. What do I need to know?
+
+**The following content is for the documentation on jamulus.io only, not for the Jamulus software!**
+
+If you aren't comfortable with Pull Requests, commits, etc. just open an issue. We will then take care of your changes. If you want to do the changes on your own and open a Pull Request, follow these instructions:
 
-`[language code (e.g. en)] {short description of your changes}`
+1. Fork the repo (there's a fork button on the top right of the GitHub page)
+2. Decide which branch you have to commit your changes to (rule of thumb: everything which might need translation should go to the `changes` branch, typos should go to the `release` branch; more information can be found in the [CONTRIBUTING file](https://github.com/jamulussoftware/jamuluswebsite/blob/changes/CONTRIBUTING.md)). Create a new branch from the up-to-date branch you chose
+3. Make your changes
+4. If you did the changes offline, push the new branch to your repository
+5. Submit your Pull Request, give a short description of your changes and link the issue you opened
+6. Wait for a review and a merge
 
-See the [Website GitHub repo](https://github.com/jamulussoftware/jamuluswebsite) for further information.
+**Hint (for git):** *Do not merge your work* into your local `changes` branch, only keep it in sync by pooling from the remote Jamulus website repository. Create a new branch for your proposed changes.
+If the `changes` branch is modified before submitting your request, keep the local `changes` branch in sync by pooling from the official one, merge the local changes branch into your working branch, resolve conflicts, push your changes and create the Pull Request.