How to automatically post issues when an English md is modified in the official guide

[BlueCutOfficial]

Need
We want to know when we have work to do.

For instance, when this repo has been created, the version in guides/release we plan to translate is Ember 4.7.0. Now, when Ember Learn team will publish the guide for Ember 4.8.0, we want to be able to detect what templates were changed in this new version, so we have to rework the translation.

First ideas
The perfect diff for us would be a diff between the English version our translation is based on and the new English version of the official guide. Comparing both English versions will point out the purpose of the change and highlight what needs to be rephrased in French.

To do so, we have:

• A branch ref-upstream that corresponds to the upstream branch our translation is based on.
• A git command that writes in a diff file the changes in upstream/master compared to the current branch (would be ref-upstream) in the scope of guides/release folder (which is the only folder we are interested in):

git diff -R upstream/master -- guides/release > diff

Issue
We need to figure out how to use the ideas above ⬆️ to actually imagine and implement a convenient workflow to follow the official guide changes.

[KamiKillertO]

Maybe we can make a CRON with Github action that runs the above command every day or week

[BlueCutOfficial]

Yes 👍 I would even suggest every month or less because the release pace for a new documented Ember release is not that fast. Being able to generate the diff with a CRON could be a nice first step just by itself.

Next, there are many aspects of the issue we can think about: once the command is launched, what do we do with the result? The long-term idea would be to parse the diff in order to automatically open Github issues that follow a given template.
Also, we would need to find when the rebase of upstream/master on ref-upstream happens in our workflow. Is it when all the changes have been considered? Is it at the beginning of the cycle when the issues are created?

[BlueCutOfficial]

Meanwhile for now, the guide is not entirely translated and we don't have a tool to automate the follow, so here is the manual way to apply the changes.

Generate a diff between our current English version and the upstream English version:

git checkout ref-upstream
git fetch upstream
git diff -R upstream/master -- guides/release > diff

Create a working branch to apply the diff:

git checkout master
git checkout -b catchup-x.x.x (the new Ember version)
git apply diff

=> The command fails to apply the patch on files that have already been translated into French.

• For each file that couldn't be patched:
  • If the change is very simple, modify the French file.
  • Else, open an issue (with the template for files to translate) and copy the diff and the Ember versions so we know what we have to do.
  • Then delete the corresponding diff block from the "diff" file so it doesn't get in the way of git apply diff next time you run it.
• Once all the "unpatchable" diff have been removed from the "diff" file, launch git apply diff again.
  => It will automatically apply all the changes in English files.

After that, make sure to update the branch ref-upstream for the next time

git checkout ref-upstream
git reset --hard upstream/master
git push origin -f ref-upstream

[BlueCutOfficial]

I was able to automate the first set of commands to generate the diff file. Now I start how to transform the diff to respect the our codebase scaffolding (guides/*.md instead of guides/release/*.md)

[BlueCutOfficial]

My script is able to perform all the local actions:

• it creates a catchup branch
• it generates a diff and applies automatically the changes English to English
• at the end of a process we have a few children diff file for the English to French that can't be applied automatically

Now I am working on posting issues on Github.

[BlueCutOfficial]

It's alive #215! Not a CRON for now, but at least one command I can execute.

[BlueCutOfficial]

I think I am going to close this issue in favor of #220 (solved by #236) then if there are more needs (like a CRON) we will open a new issue.