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.