Using single PRs for minor fixes affecting all localisations

[shurup]

Hi everyone! I'd like to raise the controversial issue we discussed a few times already, but it still sounds relevant to me… Do we really need to bring any changes to each localisation in separate PRs? Just recently, I witnessed a couple of good examples where I believe we don't need all that extra effort and resources:

• Upgrade mysql image version to allow multi-arch env #50822
• fix: change the ports scope in the network policy examples #50994

Both PRs only bring minor technical changes to listings. Specifically, the first one changes the container image version of mysql that will be deployed, and the second one fixes the YAML formatting issue. Both authors were requested to limit their changes to the English version only, as we usually do. Then, a bunch of new PRs will be raised (for each localisation, for each such case), increasing the number of commits, PRs, deploy previews… — essentially, the amount of computing resources, time and people involved in all of this. As we can also see, each time we have to explain these things (i.e. "please, split your PR into separate PRs") to new contributors. Is it really worth that? Personally, I feel that the current workflow generates a lot of unnecessary burden.

Surely, the scope of changes allowed for this simplified approach (via a single PR affecting all localisations) should be strictly limited.

• The two most common cases I see as applicable are: listings (as in the examples above) and links (to other doc pages or outdated websites).
• Perhaps something related to meta tags and formatting should also be covered. Not sure whether it's a common case now.
• Definitely, anything affecting the localised text can't be changed following this simplified approach.

Additionally, we can add some organisational workflow to such changes, e.g. by inviting all the localisation teams to see these PRs. Maybe even asking them to LGTM the PRs, yet limiting the timeframe when it's possible to do so — otherwise, we'll simply be stuck with minor changes for everyone since some localisation teams don't have enough resources to process them quickly.

I think the biggest argument here is that if we allow such a simplified approach, some localisation teams' specific (already established?) workflows might be affected. If so, can't we agree with the teams that their workflows should consider this rule for a good cause? Would it be too difficult to implement?

[Andygol]

Oops. That the case in favour to use Localization Translation Platform that tracks and apply such changes effortless.

RE: #45209 and #45756

[seokho-son]

Hi @shurup, I agree with your concerns and, overall, I support your proposal.
I also believe the current approach—splitting even minor, localization-unrelated changes into multiple PRs—needs to be improved. In fact, there are cases where certain changes don’t actually require review from localization reviewers. This PR could be one such example.

It would be ideal to simplify the process, but the main issue is that each localization team currently follows its own workflow—especially when it comes to syncing outdated content with the English source.

For example, the Chinese localization team has an internal policy that even minor edits to a document must trigger a full update of the entire page. Some teams, such as the Korean localization team, work exclusively on a separate working branch and only accept hotfixes into the main branch.

These teams have established and maintained their workflows effectively for a long time, so asking them to change what has been working well won’t be easy.
However, I think it's time we revisit this topic and start a new round of discussion.

Of course, going forward, using a localization platform like the one introduced by @Andygol might be a good solution too—though updating existing workflows for established teams may not be straightforward.

[Andygol]

though updating existing workflows for established teams may not be straightforward.

Unfortunately, we haven’t had a chance to explore these platforms yet. There’s nothing we can do for the teams that are already set up.

[shurup]

Below I'm providing an impressive recent bunch of unnecessary PRs we're getting until our policy/workflow on trivial updates changes. They all populate modifications in numerous examples (YAML files) or metadata/headers accepted in the original version to one specific localisation (Russian).

• [ru] sync with PR 41715 #51787
• [ru] sync with PR 32353 #51788
• [ru] sync with PR 36596 #51790
• [ru] sync with PR 43688 #51791
• [ru] sync with PR 37982 #51792
• [ru] sync with PR 38920 #51793
• [ru] sync with PR 51282 #51794
• [ru] sync with PR 37484 #51796
• [ru] sync with PR 47724 #51797
• [ru] sync with PR 45871 #51798

It seems that @dkarczmarski somehow automated(?) producing such PRs. Any comments from him on that will be much appreciated here 🙏

[dkarczmarski]

@shurup
Hi :)
It’s not automated - I did it all manually.
I generated a list of all files that need to be synced with all PRs. Some files need to be synced with multiple PRs, and I didn’t touch those.
But there are some trivial ones, and I created sync PRs for them.

I attached the report from my tool with files that neeed to be sync.
ru-report.tar.gz

[dkarczmarski]

@shurup
I'd like to add my comment. You wrote that it was a bunch of unnecessary sync PRs :) I thought it was the community's responsibility to keep these files up to date. I didn’t mean to cause any trouble - that was never my intention.
Since the sync process worked so well for the [pl] translation, I decided to experiment a bit and synchronize some very trivial cases.

Over the past year, I’ve created several translations in the [pl] language directory.
In my opinion, maintaining translations is similar to maintaining unit tests - it’s easy to create them, but they can be hard to maintain. That’s exactly why I created two tools to make the process easier.

The first tool ensures that all my [pl] translation files have the same structure as the original English files - this means the structure is preserved and line numbers match the [en] version.
When there’s an update to the English files, you only need to look at the diff to see exactly what needs to be updated in your translation.

The second tool generates a list of files that need to be updated. It analyzes Git history and commit dates to identify the changes that require attention.

I’ve created many sync PRs for the [pl] language, and it was easy because the translation files match the line numbers of the English files.
When a new PR is opened for [en], it becomes much easier to update only the relevant parts in the translation.

The second tool will be ready soon - it generates a list of all changes for translation files. In my opinion, it can make keeping translations up to date much easier. It already works well for the [pl] translation.

[Andygol]

Hey @dkarczmarski, would you be up for using CrowdIn to track, update, and review/approve translations? Doesn't matter what language. See PNPM for refernce https://crowdin.com/project/pnpm.

re #51006 (comment)

[shurup]

You wrote that it was a bunch of unnecessary sync PRs :) I thought it was the community's responsibility to keep these files up to date. I didn’t mean to cause any trouble - that was never my intention.

Oh, my bad! I'm really sorry I said it this way! I didn't want to mean you did anything bad. You did everything perfectly, according to our current policy. What I meant was that I'd like to see some improvements that will allow us to avoid extra PRs in the future. That's what we discuss in this thread, and we're still far from having everyone agree with this idea — even in general, not to mention particular details on how this can be executed. Anyway, it has nothing to do with your existing PRs; they are perfectly fine as they are now!

Thank you very much for sharing this information on your approach and the tools you use! It's really helpful, and I believe it's something other localisation teams might want to learn from or even adopt in their workflows.

[dkarczmarski]

@shurup

You wrote that it was a bunch of unnecessary sync PRs :) I thought it was the community's responsibility to keep these files up to date. I didn’t mean to cause any trouble - that was never my intention.

Oh, my bad! I'm really sorry I said it this way! I didn't want to mean you did anything bad. You did everything perfectly, according to our current policy. What I meant was that I'd like to see some improvements that will allow us to avoid extra PRs in

You don't have to apologize - everything is okay :) I understood your intention in your comment :)

My partial sync PRs might have caused some trouble - I understand that.
You're right that it's better to create one larger PR with all updates, but I did it that way because I thought it would be easier to process a few smaller PRs than one big one. Maybe I was wrong.

I chose some trivial cases as an experiment. It might not have gone as well as I thought :) Maybe I was too eager :)