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 #28 (comment)

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: jamulussoftware/jamulus#77 (comment)

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:

#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.

[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 Version control in Jamulus documentation #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: jamulussoftware/jamulus#77 (comment)

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:

jamulussoftware/jamulus#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.

[gilgongo]

The translate branch is set up and has the correct permissions for translators (some have push access now).

OK but @ignotus666 wanted to have the translation branch name in capitals with emojis and things so translators could see it more easily I think. Can you re-name it with fire emojis or something?

[ann0see]

Puh. I don't know anything about emojis in git (I'm afraid it would brake the branch). I think @ignotus666 didn't mean that. He wanted the commits to have capital letters.

[ignotus666]

We need animated fireworks emojis, preferably with sound. And things.

Nah. This:

He wanted the commits to have capital letters

[gilgongo]

OK so I'll create a new translation branch for the latest release (using a suitable shouty name), commit anything that needs changing into "changes", and then squash merge changes to that new translation branch, yes?

[ann0see]

So I'll create a new translation branch for the latest release

I'd open a PR to the translate branch since it should be up to date

Then squash merge changes to that new translation branch

Yes. You should ping the translators there too. They will then comment on a merged PR.

[gilgongo]

I'd open a PR to the translate branch since it should be up to date

Sorry - just to be clear: you mean I should not create a new translation branch? I thought we needed to name it loudly so translators could see it?

[ann0see]

The branch already exists it's called translate and people like @trebmuh have push access to this branch already. We could also create a separate branch, but I don't see any advantage for doing so.

We mention the translators with @jamulussoftware/translators

[gilgongo]

OK that's done.

[ann0see]

Great. So translations can start (based on the content of the new PR)

[ann0see]

@gilgongo Did you include jamulussoftware/jamulus#731?

I've added a brief description to your PR but we need to check if everything is ok and then mention the translators.

[ann0see]

I've now moved the issues for the specific languages to the new GitHub discussion section since they aren't issues and will not be closed at any time. I hope this helps to unclutter the issues tab

We should clarify when to open an issue, and when a discussion.
My suggestion: everything which can't be resolved (like the ongoing translation process which will repeat multiple times) should go to discussions.

Issues should really be problems and focus on the topic of the issue title. If there's a new idea --> open a new issue

jamulussoftware/translators should only be for announcements from gilgongo to all translators (e.g. if the translation phase starts. Talk about the changes should take place in the Pull Request he merged since they can be resolved).

What do you think?

Edit:

Don't want to loose this comment by @ignotus666 (which is quite difficult ;-))

Translations should not have content that isn't in the English version yet. The English version takes the lead in 'changes' - that's why there are new documented features that aren't in the 'translation' branch. We're going to wait until all translations are level with the English version in the 'translation' branch. Then, when the next release approaches, all new text and edits committed to 'changes' are merged into 'translation' in a single commit (via 'squash and merge') and translators update their languages in that branch.

In short:

Translators should only make commits to 'translation' and their reference English version is the one in that branch. No new content can be added in this branch, in any language.

Any modifications or additions to the documentation must first be made to the English version in the 'changes' branch. This branch is for changes to the English version only.

[ann0see]

I think, we now have a process which is at least briefly documented. Can we close this now?