Version control in Jamulus documentation

[ann0see]

Currently we suffer from unstructured editing, have different versions in languages,... We should discuss how we solve this problem (= ensure every language is up to date).

To make development easier and faster, @gilgongo suggested to make a new branch. I think that's a good idea. We could split it into 3 branches: main: the branch which gets built to github pages. We only submit changes here if everything was approved. Translation: The step before approval. Here translation begins. No changes Development: Active development, restructuring,...

So a normal workflow would look like this:

1. Add a new page (english only): commit to the development branch.
2. After a period of time it gets merged into translation for the translators
3. If everything was checked, we merge it into main.

Of course we could also create a "development" and a "translation" branch while the "translation" can not be changed content wise.

Originally posted by @ann0see in https://github.com/jamulussoftware/jamulussoftware.github.io/pull/28#issuecomment-719692886

Another option would be the projects tab on github (we could document changes and todos there).

[ignotus666]

Sounds good to me. The Spanish translation is currently up to date with the English version.

[gilgongo]

Do we need to avoid peppering the development branch with small changes? Or is that not an issue if we do a regular merge into the translation branch - I would imagine that means translators then get one diff to work on? If so then that's good. I'd like to be able to comment changes too so that we can communicate why they are being made, and maybe get feedback on improvements to the changes.

BTW I'm assuming we do the development to translation merge at some predictable interval, if only to send out a reminder to the translators. Monthly? Or maybe perhaps a week or so before a release, which is what Volker does with the app?

[ann0see]

I think we should follow the release period of the app (for me it makes sense). I don't know how much work all these branches would make (especially management, of pull requests,...)

[gilgongo]

Would tags be easier/better for this? I don't actually have any experience with tags so maybe not, but could we tag changes on a "translation" branch with the name of the upcoming release, thereby only having two branches?

[ann0see]

We could probably also use milestones. They're better suited for that.

We could assign translators to new PRs they would then be able to translate all files before a merge.

Nevertheless, I think a fixed period for translating following the app is better and easier for translators.

[ann0see]

@gilgongo said: #40

I'm not sure if we resolved exactly how we'd be doing documentation changes other than saying we'd do them all prior to each software release. I'm keeping a list in a Google doc for the moment (and will add this). But what are the options?

1. Somebody collects up all the PRs that we want to action (some might not be ones we want), mails the translators with the list of PRs to look at.

2. Collect up all the PRs we want to do and make a single issue describing all the changes in a way that makes is easy for translators to do.

3. Don't tell people to raise PRs (although they can if they want I guess) and tell them to suggest changes as issues, then do 2.

4. Some other method?

[ann0see]

I'm keeping a list in a Google doc for the moment (and will add this)

I wouldn't say that's optimal. I think changes should be visible on GitHub for everyone (maybe with Milestones/Projects/...).

We can mention all translators since they belong to the jamulussoftware organisation at once \@ jamulussoftware/translators

[gilgongo]

I wouldn't say that's optimal.

Yes but I'm only doing that until we work out a way of batching changes and communicating them properly. Otherwise I'll forget :-)

So of the options I've listed, which do think might be best? I assume we don't want to spam the translators with PRs for individual changes (like this one), so that implies some form of collection process first.

From my POV, I think 3 would be the most democratic, since only tiny proportion of Jamulus users know what a PR is.

[gilgongo]

New release date set for Nov 22nd: https://github.com/corrados/jamulus/issues/77#issuecomment-727604858

I've got a bunch of changes to make here. I think they're all uncontroversial but I'm not sure how some of them will be done exactly until I do them.

I'll do them as soon as I can then message the translators with a summary and we'll see how that works?

[ann0see]

1-6 No problem. 7: we already link to sourceforge but not to the forums. Will we add a new button or change the link (which might be confusing since the SF logo doesn't imply that there's a forum behind that)

7-8: ok

9: think about a redesigned manual. Already for this release?

The translators should also check if their translation is really up to date with the English version. There might still be some differences.

[gilgongo]

For 9 - yes. Might benefit from a better layout maybe but for now I'll just update as it is.

[ann0see]

I think after #42 and your changes are finished we will need a complete documentation freeze to allow translation to begin.

[ann0see]

@ignotus666 said

The problem is this: you have to trawl through all the commits, some often applied to the same document but days apart. And as I see lots of commits to the 'main' branch, I find myself checking all of these in addition to the GH branch in case there are changes there I should take into account... It would simplify things a lot if, when the release date approaches, translators could view all the changes in one single 'bulk' commit (with 'squash and merge'). This would require two 'layers' of branches before the main branch:

1: All commits are made here during the 'freeze' period. 'main' only gets touched to make spelling corrections or to add urgent edits that can't wait for the release.

Branch 2: When the release date approaches, all the commits to Branch 1 are merged into one with 'squash and merge' and pushed to Branch 2, which is where translators can view all changes in one go, without having to open each separate commit. They in turn commit to this branch.

Then 'Branch 2', with all its updated docs, gets pushed to 'main' for the release date.

Maybe this has already been proposed or there is a better approach already in place that I haven't managed to grasp. If so, I need someone to spell it out for me!

[gilgongo]

Ok that sounds like a good plan. I suggested a modifications branch but I don't think we agreed on that exactly, and then the new release came up so we've had do it a bit messily this time.

So, how about I do a test of this approach for the last remaining changes? That is:

1. I create a new branch called "changes-3.6.1"

2. Commit the changes to that branch.

3. Do a squash and merge to a branch called "translation-3.6.1" (no idea how to do a squash and merge btw)

[ignotus666]

Yeah, we could give it a try.

I only discovered squash and merge by chance and haven't used it, but it looks like a handy thing to do what I propose. When you go to merge a pull request, on the right of the green button there's an arrow with a dropdown menu:

[trebmuh]

Copy/pasting from the "team's discussion" as @ann0see advised. (ann0see: for clarity I've erased the post in the team's discussion section then).

(Please, note that I didn't read this discussion yet and will do later today.)

---

Hi all.

I'm working on translation for larger scale software (I'm the French translator for Audacity as an example). I recommand a few translators rules for here.

For translation purpose, there is an "origin" text which is the English version. The translators must not change the original wordings by interpretation because it couldn't work in a bunch of situations such as:

1. How it could work if any translators can change only in their language translation the original meaning. The translations will soon be different for each translation. How will you manage that when there will be over twenty different translations?
2. How will you manage that when there will be a change of translator for a language?
3. How will you manage that if there are more than one translator for one language (which is already the case for the French tram here), because every translator will feel allowed to put its own interpretation, and that's a very good receipt for a disaster. It's unmanageable on a long term view.

Suggested rule of thumb:

1. a translator translates and do not interprets unless it is very highly needed
2. translators doesn't try to fixes an original (English) text mistake in their translation, they report a change proposal in the original text
3. I'd recommand for managing the translation contributions as the software. We do "release". Then the master branch doesn't change but for typo fixes and we work on a "next_release" branch on the original (English) text. When needed, we decided to "freeze" the original "next_release" text, and we decide that the translator get one week to translate (one week is what we do for the software translation). After this "translation week", we merge all the work done (in the original text and the translations) in master... and we go on for the next cycle. This is something close to what @ignotus666 proposed here

Feedbacks welcomed.

[ignotus666]

More or less what I proposed but IMO another intermediate branch needs to be added to what you describe - one that receives all the commits to "next_release" consolidated into a single commit. This should make it much easier for translators to see all the changes made, all grouped together, instead of having to inspect commits one by one. I like the branch names proposed by @gilgongo ('changes' and 'translation') as they are descriptive.

I agree with sticking to the English 'master' version and refraining from subjective interpretations. If you think there's something wrong with the original, submit a proposal. I would also add to the list:

• Before jumping in to translate, check the status of your language and find out if anyone else is working on it. Avoid duplicating work.

• If there are several translators working on a single language or part of the translation has already been done, try to keep the terminology, tone and style consistent. Try to discuss it with other translators before overwriting or correcting their work (unless it's an obvious mistake).

• Public discussions should be in English. We're translating from English so sufficient command of the language is taken as a given.

[gilgongo]

OK so I've got a couple of minor remaining changes on this pull request:

https://github.com/jamulussoftware/jamuluswebsite/pull/49

I can only squash and merge to the "base branch" (is that "main"?) though. Should I do that?

EDIT: Maybe I need to do it on the command line? So first create a new branch (translation-3.6.1) then:

git fetch origin
git checkout -b changes-3.6.1 origin/changes-3.6.1
git merge translation-3.6.1

git checkout  translation-3.6.1
git merge --no-ff changes-3.6.1
git push origin  translation-3.6.1

Is that right?

[ann0see]

I think that's right. I'd rename changes-3.6.1 to development and translation-3.6.1 to translation.

Basically it's very close to the first proposal in this issue.

What would be a normal process?

On User Max wants to change something {
if change is a typo or similar {
  commit to main branch
} else if change is something which needs to be translated
  commit to development branch
}

On one week + one day before release {
  open a new pr from development to translation with a mention of @ jamulussoftware/translators
  Proposal: automatic squash and merge after 1 day (to allow last discussions) from development to translation
  let the translators translate the changes
  merge translation into main
}

I fear that these branches could lead to confusion and an overly complicated workflow.

I can only squash and merge to the "base branch" (is that "main"?) though. Should I do that?

Since you're not a translator, I think that's alright. BUT: we are currently in translation phase. The spanish version will not have this update. Any thoughts on that?

[ignotus666]

@gilgongo: When you open a PR on (let's call it) 'development', you can choose where you want it merged to . By default it's set to base:master, but you can change that to whatever branch you want:

You make the PR and then, the next 'merge' step is when you set it to 'squash and merge'. I just tested it with my own repo and it's quite simple.

@ann0see: I don't think it necessarily has to be too confusing. The wiki maintainers only make changes to the 'development' branch, and translators should only focus on the 'translation' branch. As in the process you describe above, when the release date approaches the maintainers merge 'development' into 'translation' and translators get a message about the upcoming release and make their commits to the 'translation' branch. When the day arrives, the maintainers merge it into 'master' and that's it.

[ann0see]

The PRs could even be automated somehow maybe with something like https://peterevans.dev/posts/github-actions-how-to-create-pull-requests-automatically/ or https://github.com/palantir/bulldozer and https://probot.github.io/apps/todo/

It would be great to have an automated workflow like this:

corrados mentions a new planned release this opens an issue and pr labeled for-upcoming-release here if this pr is merged a bot automatically mentions the translators in the opened issue to let them start translating the documentation

on the release day and if everything is approved the pr is automatically merged.

On corrados/jamulus an action automatically compiles jamulus and uploads the binaries to SourceForge or better GitHub (but as far as I know, corrados wants to stay on SF)

[gilgongo]

@gilgongo OK but I've made the PR now so is it too late to tell it to where to merge to? I think I can do it on the command line though.

@ann0see I'll name them "development" and "translation" in future then - I just wondered if the version number might make things clearer but maybe it's just more complexity.

[gilgongo]

this opens an issue and pr labeled for-upcoming-release here

Does this imply all the changes doc maintainers do have to be on a single PR? The way things tend to work with doc updates is that occasional changes are sometimes made and un-made quite often all over the place, so putting them all onto a branch then merging that seems the better way to go. But I may have misunderstood.

[ignotus666]

@gilgongo I think you can just cancel the PR and start again.

[ann0see]

Our ideas are almost the same. The only difference is that I propose to also open an issue for each upcoming release (this issue would stay open until everything is done) to allow a discussion throughout the whole release period.

[gilgongo]

OK so the remaining changes for 3.6.1 are on the branch "translation-3.6.1" now.

Let's see how that works for people and we can merge that branch into main as proposed (when the translations are done).

Hope its OK to do the other changes in the messy way with the PRs and main branch changes meanwhile?

[ignotus666]

If new changes will affect translations I'd prefer if you could do them to the 'changes' branch. We also need to get the other translators on board and starting from next week do a hard 'reset', all following the same guidelines and making sure we're starting from the same point, because we run the risk of drifting out of sync.

[ignotus666]

Just updated the docs in Spanish on the 'translate' branch. To make the 'squash and merge' commit (as it's the reference for translators) visible, as it gets buried by subsequent commits, I'd name it something descriptive in block capitals - something like 'TRANSLATION-3.6.1'.

[gilgongo]

If new changes will affect translations I'd prefer if you could do them to the 'changes' branch.

@ignotus666 Sorry, not sure I understand. I'm not planning to make any further changes - or do you mean you want all the changes for this release (that I've put into main) also in the changes branch now (and re-merge to translation-3.6.1)?

Will use block caps next time. BTW I'm a bit out of my depth with all this git stuff - how do I see what you're seeing so I can get an idea of what you mean by "buried"?

.

[ignotus666]

Sorry, not sure I understand. I'm not planning to make any further changes - or do you mean you want all the changes for this release (that I've put into main) also in the changes branch now (and re-merge to translation-3.6.1)?

Ah, ok - I thought you wanted to make some more changes. If not, then don't mind me!

Will use block caps next time. BTW I'm a bit out of my depth with all this git stuff - how do I see what you're seeing so I can get an idea of what you mean by "buried"?

Say there will be no more edits to 'changes' and you make the 'squash and merge' commit to 'translation'. The translators have to check for that commit in the list, and as they add their own, the list will grow. A translator starting their work say a couple of days later will have to scan the list looking for the one containing the changes they have to use as a reference, so if it has a standard name in block capitals it will be easier to find. Here's a screenshot of what it looks like now (a very short list), but it could look a lot longer:

[ann0see]

I now updated the german translation (it wasn't much work. But I went from file to file to check if everything is the same. Nevertheless, german is not a full translation and I still don't know if I got all the changes). Therefore the new method will be much clearer and better.

I suggest @jamulussoftware/translators @SmuSmu to recheck and update their whole translations now to ensure they are still in sync with the English version. They should write down everything they would like to change in the english version and open a new issue with their proposed changes.

Edit: wrong mention.

[ann0see]

I've now opened a pr with some changes I made which can be discussed (this would be the official new way to go, I think (merge into changes)).

The main branch is now protected (PRs will need a review)

[gilgongo]

@ann0see By "next release" in the PR, do you mean the one this weekend? Is that going leave enough time for the translators?

[ann0see]

No. not the one for this weekend.

[gilgongo]

Just checking: I assume that if we see issues in main that don't affect translation we can just commit the fix directly to main, is that right? I ask because I've just seen that https://jamulus.io/wiki/Software-Manual has duplicate headings.

Or do all changes need to go through the new "changes > translation > main" route?

[ann0see]

I think it depends. Since it's a fix only for the english version, I'd say it's alright. IDK if git likes that

[gilgongo]

OK so git let me commit that back to main. But of course now we have an un-fixed version in changes and translation. So I guess I need to do it in changes too, since we're keeping that branch going permanently. I assume we'll delete translation-3.6.1 after the merge to main though so I can ignore that?

[ann0see]

I'd leave it like that. (I already made a "wrong" commit to changes instead of main for the sitemap fix (which could be fixed by adding https://jamulus.io before the site url)). Furthermore I also disabled the minifier for the sitemap, but IDK if that does anything good.

[gegeweb]

@trebmuh say

Suggested rule of thumb:

1. a translator translates and do not interprets unless it is **very highly** needed

2. translators doesn't try to fixes an original (English) text mistake in their translation, they report a change proposal in the original text

3. I'd recommand for managing the translation contributions as the software.  We do "release". Then the master branch doesn't change but for typo fixes and we work on a "next_release" branch on the original (English) text. When needed, we decided to "freeze" the original "next_release" text, and we decide that the translator get one week to translate (one week is what we do for the software translation). After this "translation week", we merge all the work done (in the original text and the translations) in master... and we go on for the next cycle. This is something close to what @ignotus666 [proposed here](https://github.com/orgs/jamulussoftware/teams/translators/discussions/1/comments/22)

Agree and follow (and understand why) this rule now. (It took a little time...)

But, For the point 2, if there is a mistake in the orginaly, especially if that is a typo or wording which distorts meaning: the good way shouldn't it be to fix the mistake on both (EN and translated) and include the both on the PR?

For the point 3, how to deal with the realease/next-realease process if that is a new translation (as our works on French is) wich come during realease pocess (the freeze before publishing)? What about the new pages not yet reviewed at time? IMHO, we should be able (and have a process for) to publish these after review and merge accepted. Without having to wait the next software and doc release. No?

[trebmuh]

Agree and follow (and understand why) this rule now. (It took a little time...)

Thanks for that.

For the point 2, if there is a mistake in the orginaly, especially if that is a typo or wording which distorts meaning: the good way shouldn't it be to fix the mistake on both (EN and translated) and include the both on the PR?

I'd say no. You're probably thinking right now that "it would be quicker" because you're thinking from your inner point of view from a situation you probably saw while translating into French (I'd bet for the macOS/Macintosh one as a good example). But here is another point of view to take in consideration: if, let's say the Belarusian (I'm sure we will have one one day!) is finding a typo in the English version and then decide to fix it in his translation PR. What are the chances for the French translator (as an example) to notice this while this "fix" will be lost inside a big Cyrillic writings PR? Chances are much higher if the fix is another PR. We should go for a PR code-naming rule for this, such as (open proposition)

"[English fix] blablabla-description". Then all translators would understand what it is about and update their translation. I understand it can make you thinking and/or feeling that "you would go quicker alone" and that would probably be true, but that's the cost of working in a team I guess.

About point 3, I'm unsure. I understand your point, but it mostly apply because we're on a transition phase with the French translation. It could be quicker to do something like you are proposing but it would push more pressure on the merger's shoulder (gilongo and ann0see). I'm fine with the translation being merged at the same rate. I can keep my frustration of not seeing it online straight away because I know that Corrados is releasing pretty often (roughly every 3 weeks). Thoughts?

[ann0see]

Coming back to version control.

I think we have to clarify how we work.

I posted this in the french translation thread.

---

So a normal process would look like this: You want to change something. First ask yourself some questions:

0. Is the language of your content already online and existing?

No: Will discuss this later (since you introduce a new language). Yes:

1. Be clear if your change needs translation

No: A fix which doesn't need to be translated (e.g. typo) --> Commit to main. It will go live a few minutes after the PR is merged Yes: A fix which needs to be translated --> Commit to changes since others will need to translate it. It will be part of the next release.

2. Be clear if there is an update going on

You can see this if we ping the translators in a pr from changes to translation.

If yes: 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

New language

1. Open an issue like this one
2. Follow the instructions to add a new language in the /README.md file on the changes branch.
3. Push the translated content to a branch we should discuss in #31 (probably translation) by opening a PR.

---

At least that's what I think the process works like.

[ann0see]

@gilgongo @ignotus666 Sorry for the strange testing and various PRs on the repo. Since I just realized how out of sync the changes branch with the main branch was, I integrated an automatic updating process. Every PR to main which is merged, should now automatically open a new pr to changes (like #132) to keep this branch in sync. I use this action: https://github.com/gorillio/github-action-cherry-pick

[ignotus666]

No problemo!

[ann0see]

Unfortunately it did not succeed this time. Let me make a few changes to other files.

[ann0see]

Yes. I think it only supports one commit alone. So maybe we should have done squash and merge.

Maybe the process has to be simplified (before each new release of the documentation, we merge main into changes (and fix conflicts), after that, we open the pr to translation (which is before that synced with main), and then ping the translators). Currently the diff between main and changes is quite clean.

[gilgongo]

OK so Volker wants to get the next release out this weekend: https://github.com/corrados/jamulus/issues/77#issuecomment-740015722

So do we squash merge the changes branch into a new "->>TRANSLATION 3.6.2<<-" branch now?

[ann0see]

Probably yes. Please merge release into changes before (and we should also take care of the new knowledge base)

[ann0see]

And the translation branch should be updated too.

[gilgongo]

It says "changes" is up to date with all commits from "release". So I don't need to merge it?

I had assumed I'd create a new branch for translation (with the version number in it), and then squash merge "changes" to that. But do we instead maintain one "translation" branch all the time?

Before I do that though, I have to add one thing to changes for this release:

https://github.com/corrados/jamulus/issues/731

Also, do we need to do anything for knowledge base? Can't we leave that until later?

[ann0see]

Also, do we need to do anything for knowledge base? Can't we leave that until later?

Agree. Leave it until later.

I have merged release into translate (so the diff should be almost clean).

But do we instead maintain one "translation" branch all the time?

I'll leave it up to you. The translate branch is set up and has the correct permissions for translators (some have push access now).

Before I do that though, I have to add one thing to changes for this release:

Ok. Then we must wait. I suggest, you open a pr from changes to translate verify that translate is in sync with release again, merge it and ping @ jamulussoftware/translators in there.

Please add a statement that issues in the english translation not introduced by these changes should be raised in a separate issue and that the content of this pr should focus on the current changes (if there is a typo for these specific changes which only affects the english version, they can comment on this pr). If something is only related to a specific language, please open a pr to the translate branch and discuss the changes there with the other people of the translation team. This keeps the discussion under the PR tidy and focused.