From e3578e554b5ba4930d6aef07dbb4d2f86f1d4020 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Sun, 28 Mar 2021 16:17:32 +0100 Subject: [PATCH 01/14] Update CONTRIBUTING.md Make this a general overview. Make README.md the instructions about what to do with repo. --- CONTRIBUTING.md | 42 ++++++++---------------------------------- 1 file changed, 8 insertions(+), 34 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 71931dc5e..d1b5a1e48 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,41 +1,15 @@ -# Contribute to the documentation -We really appreciate your support! +# Helping out with Jamulus -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. +We’d really appreciate your support and welcome help with proofreading, improvements, web design, and translation. -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. +Have a look at [README.md](https://github.com/jamulussoftware/jamuluswebsite/blob/changes/README.md) for more information. And if you’ve not seen it already, the [general overview](https://jamulus.io/wiki/Contribution) to getting involved. -If this is the case, please subscribe to the issue and explain your proposal. +## Want to help translate? -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. +To get involved in making updates or translations for jamulus.io you will need a GitHub account and be familiar with GitHub in general. If you want to get more involved, you’ll need to be familiar with the use of git on the command line, as well as Jekyll. Note that translating the Jamulus application itself is done by a different process, but you are welcome to help with that too. Introduce yourself on the [GitHub Discussion](https://github.com/jamulussoftware/jamulus/discussions) and say what you’d like to do. -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. +## Want to add a new language? -Pull requests/issues for the website should have a title which looks like this: +Great! First [open an issue](https://github.com/jamulussoftware/jamuluswebsite/issues) with the title `[Translate] yourLanguage` and introduce yourself. We will then help you to set up the relevant language files. -`[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. (If you wish to, please do not add your translation to your commit, but add a comment with the translation in your Pull Request). 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` +### Please also note that discussions should be in English so as to be open to all. From 9f01440c22687f2cb47fa2ee44375e860a7690f8 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Sun, 28 Mar 2021 16:19:37 +0100 Subject: [PATCH 02/14] Update README.md Make this work with CONTRIBUTING.md so users know how to use the repo. --- README.md | 79 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 51 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index f54a20e7c..46ecce216 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,67 @@ # Jamulus Website -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. +This is the content repository for [jamulus.io](https://jamulus.io). Text appearing in the Jamulus software application itself is part of the [main code repository](https://github.com/jamulussoftware/jamulus). The web site is built with Jekyll and Fox-CSS. -## 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 +### Please also note that discussions should be in English so as to be open to all. -## Contribute a translation +## Making changes to the English version -**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/jamulus/discussions and participate in it** +(See the translation process later in this document if you want to get involved with that.) -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: +Make a fork of the Jamulus repository (button at [top right here](https://github.com/jamulussoftware/jamuluswebsite)). In your fork, you can edit the website pages (or of course use git on the command line if you prefer). When you are done, create a pull request that we will review, translate and publish in the next release. -- 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 view the website offline one your own machine, you will need to clone it locally and use Jekyll to build it. Please ask on [in the discussions](https://github.com/jamulussoftware/jamulus/discussions) for help with this if necessary. +## Formatting and style -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.) +We use GitHub markdown to format the basic text. Have a look at the markdown in existing pages for examples. -### Adding a new language +Note that we use British English spelling and grammar conventions. -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. +Adding pictures -Have a look at the README.md files in these folders. +Use the `{{site.url}}` variable to call an existing image in the corresponding directory for that language. This ensures the correct URL is used: -## Tech +` Date: Mon, 29 Mar 2021 11:51:36 +0100 Subject: [PATCH 03/14] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d1b5a1e48..79b772d16 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Helping out with Jamulus -We’d really appreciate your support and welcome help with proofreading, improvements, web design, and translation. +We’d really appreciate your support and welcome help with for example proofreading, improvements, web design, translation. Have a look at [README.md](https://github.com/jamulussoftware/jamuluswebsite/blob/changes/README.md) for more information. And if you’ve not seen it already, the [general overview](https://jamulus.io/wiki/Contribution) to getting involved. From eef4b83352a899a1a7bc193afebba769d31223f5 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Mon, 29 Mar 2021 12:02:35 +0100 Subject: [PATCH 04/14] Update README.md --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 46ecce216..dd50d4fda 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,15 @@ This is the content repository for [jamulus.io](https://jamulus.io). Text appear ## Making changes to the English version -(See the translation process later in this document if you want to get involved with that.) +(Note that any significant changes must be made to the English first. See the translation process later in this document if you want to get involved with that.) -Make a fork of the Jamulus repository (button at [top right here](https://github.com/jamulussoftware/jamuluswebsite)). In your fork, you can edit the website pages (or of course use git on the command line if you prefer). When you are done, create a pull request that we will review, translate and publish in the next release. +To edit an individual file, you can use the Github web interface or make a fork of the Jamulus repository (button at [top right here](https://github.com/jamulussoftware/jamuluswebsite)). In your fork, you can edit multiple website pages (or of course use git on the command line if you prefer). When you are done, create a pull request that we will review, translate and publish in the next release. To view the website offline one your own machine, you will need to clone it locally and use Jekyll to build it. Please ask on [in the discussions](https://github.com/jamulussoftware/jamulus/discussions) for help with this if necessary. ## Formatting and style -We use GitHub markdown to format the basic text. Have a look at the markdown in existing pages for examples. +We use [GitHub markdown](https://guides.github.com/features/mastering-markdown/) to format the basic text. Have a look at the markdown in existing pages for examples. Note that we use British English spelling and grammar conventions. From 204faaeb7eca68c453c71f35969436b5df1c3dfc Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Tue, 30 Mar 2021 18:11:22 +0100 Subject: [PATCH 05/14] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dd50d4fda..171c74cdb 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ We use [GitHub markdown](https://guides.github.com/features/mastering-markdown/) Note that we use British English spelling and grammar conventions. -Adding pictures +## Adding pictures Use the `{{site.url}}` variable to call an existing image in the corresponding directory for that language. This ensures the correct URL is used: From 4099465ffe50c26fd9d980e2b240656b997862d8 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Tue, 30 Mar 2021 18:13:44 +0100 Subject: [PATCH 06/14] Update README.md Co-authored-by: Christian Hoffmann --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 171c74cdb..27e0d78af 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ We collect changes to the English version of the site on a "changes" branch firs 1. Changes are first made to en-*.md files and committed to the “changes” branch. 1. Once we’ve agreed to release the changes to production (usually just before a software release), we then create GitHub issues for each language, tagged for that release. You can ask questions about the work there. -1. We then squash merge changes to a “translation_[versionNo]” branch. +1. We then create a “translation_[versionNo]” branch which contains all relevant changes in a single commit for easy translation (`git branch translation_[versionNo] release && git checkout translation_[versionNo] && git merge --squash changes`). 1. Translators for each language then update any affected files in their language and open pull requests to merge them into a new branch for the release. Those pull requests are linked to the relevant GitHub issue in step 2. 1. When all translations are merged (issues will then close automatically), we merge that new branch into the trunk. From a8b2da28088257532ead563296f1f1cbbd471c84 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Tue, 30 Mar 2021 18:16:25 +0100 Subject: [PATCH 07/14] Update README.md Co-authored-by: Christian Hoffmann --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 27e0d78af..ab16ed047 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ We collect changes to the English version of the site on a "changes" branch firs 1. Once we’ve agreed to release the changes to production (usually just before a software release), we then create GitHub issues for each language, tagged for that release. You can ask questions about the work there. 1. We then create a “translation_[versionNo]” branch which contains all relevant changes in a single commit for easy translation (`git branch translation_[versionNo] release && git checkout translation_[versionNo] && git merge --squash changes`). 1. Translators for each language then update any affected files in their language and open pull requests to merge them into a new branch for the release. Those pull requests are linked to the relevant GitHub issue in step 2. -1. When all translations are merged (issues will then close automatically), we merge that new branch into the trunk. +1. When all translations are merged (issues will then close automatically), we merge that new branch into the `release`. ### Points to note From c46d980feb8ee32f81a98ec48ae45fbaf703bb67 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Tue, 30 Mar 2021 18:16:46 +0100 Subject: [PATCH 08/14] Update README.md Co-authored-by: Christian Hoffmann --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ab16ed047..bf0cb993a 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ Please do not add new or significantly modified content to a non-English .md or Please make sure you are aware of what stage of the workflow we are currently at by monitoring the [project board](https://github.com/orgs/jamulussoftware/projects/2), and on the Discord (or Matrix) discussion channel that you will be invited to join. This is where relevant deadlines and information will be posted during the translation sprint. -Pull requests for translation should have a title which looks like this: +Pull requests for translations should have a title which looks like this: `[Tag (Translation)][language code (e.g. en)] {short description of your changes}` From 18c04df4aa4c4902bb88be86cddd87150b6955f3 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Tue, 30 Mar 2021 18:16:57 +0100 Subject: [PATCH 09/14] Update README.md Co-authored-by: Christian Hoffmann --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index bf0cb993a..234549282 100644 --- a/README.md +++ b/README.md @@ -62,6 +62,6 @@ Pull requests for translations should have a title which looks like this: ## Adding a new language -Make sure to add the language to the \_config.yml file (in the languages array.) At a minimum, the main includes for the wiki (see \_includes/wiki/) have to be translated. +Make sure to add the language to the \_config.yml file (in the languages array). At a minimum, 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 also be translated. From 3892a600053a62abb2e4f9eb76bb6a8646526c36 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Wed, 31 Mar 2021 07:36:38 +0100 Subject: [PATCH 10/14] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 234549282..45b17458f 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ This is the content repository for [jamulus.io](https://jamulus.io). Text appear To edit an individual file, you can use the Github web interface or make a fork of the Jamulus repository (button at [top right here](https://github.com/jamulussoftware/jamuluswebsite)). In your fork, you can edit multiple website pages (or of course use git on the command line if you prefer). When you are done, create a pull request that we will review, translate and publish in the next release. -To view the website offline one your own machine, you will need to clone it locally and use Jekyll to build it. Please ask on [in the discussions](https://github.com/jamulussoftware/jamulus/discussions) for help with this if necessary. +To view the website offline one your own machine, you will need to clone it locally and use [Jekyll](https://jekyllrb.com/) to build it. Please ask on [in the discussions](https://github.com/jamulussoftware/jamulus/discussions) for help with this if necessary. ## Formatting and style From a53b047f276f55acbb0809d23eb32e875f7af39a Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Wed, 31 Mar 2021 07:43:59 +0100 Subject: [PATCH 11/14] Update README.md Clarifying release process. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 45b17458f..55c214248 100644 --- a/README.md +++ b/README.md @@ -42,10 +42,10 @@ We collect changes to the English version of the site on a "changes" branch firs ### Here’s the overall workflow 1. Changes are first made to en-*.md files and committed to the “changes” branch. -1. Once we’ve agreed to release the changes to production (usually just before a software release), we then create GitHub issues for each language, tagged for that release. You can ask questions about the work there. +1. Once we’ve agreed the changes can go live (usually just before a software release), we then create GitHub issues for each language, tagged for that release. You can ask questions about the work there. 1. We then create a “translation_[versionNo]” branch which contains all relevant changes in a single commit for easy translation (`git branch translation_[versionNo] release && git checkout translation_[versionNo] && git merge --squash changes`). -1. Translators for each language then update any affected files in their language and open pull requests to merge them into a new branch for the release. Those pull requests are linked to the relevant GitHub issue in step 2. -1. When all translations are merged (issues will then close automatically), we merge that new branch into the `release`. +1. Translators for each language then update any affected files in their language and open pull requests to merge them into the "translation_[versionNo]” branch. Those pull requests are linked to the relevant GitHub issue in step 2 so they can be tracked. +1. When all translations are merged (issues will then close automatically), we merge that new branch into the `release` branch, which is automatically made live on the production site. ### Points to note From 824fde983ebfd5c3d0e416e4be5ac1a156ab0e67 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Fri, 30 Apr 2021 08:06:14 +0100 Subject: [PATCH 12/14] Update README.md Add link to translating.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 55c214248..6e8efc010 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ If you want to add a new image, use .png format if possible, and if it’s not a - Getting Started - Installation pages -For translating text in the Jamulus application itself, please see this guide.? +For translating text in the Jamulus application itself, please see [TRANSLATING.md](https://github.com/jamulussoftware/jamulus/blob/master/) We collect changes to the English version of the site on a "changes" branch first. We then freeze changes prior to a Jamulus software release, and do a translation "sprint" over a couple of weeks when all translation takes place. From fbbabfb28328093b50de2444bb6fa66496eb06c4 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Fri, 30 Apr 2021 20:10:58 +0100 Subject: [PATCH 13/14] Update README.md Fix link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 6e8efc010..bf088ab85 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ If you want to add a new image, use .png format if possible, and if it’s not a - Getting Started - Installation pages -For translating text in the Jamulus application itself, please see [TRANSLATING.md](https://github.com/jamulussoftware/jamulus/blob/master/) +For translating text in the Jamulus application itself, please see [TRANSLATING.md](https://github.com/jamulussoftware/jamulus/blob/master/TRANSLATING.md) We collect changes to the English version of the site on a "changes" branch first. We then freeze changes prior to a Jamulus software release, and do a translation "sprint" over a couple of weeks when all translation takes place. From 056dd02c4e3ba253358f9789f9dfd1b2ead3c491 Mon Sep 17 00:00:00 2001 From: Jonathan <4561747+gilgongo@users.noreply.github.com> Date: Fri, 30 Apr 2021 20:17:26 +0100 Subject: [PATCH 14/14] Update README.md Add bullets. --- README.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index bf088ab85..410681c16 100644 --- a/README.md +++ b/README.md @@ -49,15 +49,13 @@ We collect changes to the English version of the site on a "changes" branch firs ### Points to note -Each page on the site has a .md or .html language suffixed version. Most of the website content is in \_includes/wiki/[langCode]. 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 +- Each page on the site has a .md or .html language suffixed version. Most of the website content is in \_includes/wiki/[langCode]. 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 -Please do not add new or significantly modified content to a non-English .md or .html file. All changes must be made on the changes branch in English **first** after being [discussed here](https://github.com/jamulussoftware/jamulus/discussions). +- Please do not add new or significantly modified content to a non-English .md or .html file. All changes must be made on the changes branch in English **first** after being [discussed here](https://github.com/jamulussoftware/jamulus/discussions). -Please make sure you are aware of what stage of the workflow we are currently at by monitoring the [project board](https://github.com/orgs/jamulussoftware/projects/2), and on the Discord (or Matrix) discussion channel that you will be invited to join. This is where relevant deadlines and information will be posted during the translation sprint. +- Please make sure you are aware of what stage of the workflow we are currently at by monitoring the [project board](https://github.com/orgs/jamulussoftware/projects/2), and on the Discord (or Matrix) discussion channel that you will be invited to join. This is where relevant deadlines and information will be posted during the translation sprint. -Pull requests for translations should have a title which looks like this: - -`[Tag (Translation)][language code (e.g. en)] {short description of your changes}` +- Pull requests for translations should have a title which looks like this: `[Tag (Translation)][language code (e.g. en)] {short description of your changes}` ## Adding a new language