solidity-docs / .github Goto Github PK

Some translator teams are targeting specific tagged versions of the compiler (for example the Turkish team wants to translate and tag 0.8.15 before moving on to translating any further changes). In this use case the team is not interested in receiving PRs each time something changes in the main repo but will still be interested in a PR covering all the changes since the last release once a new one is tagged.

And overall, even if the team is fully caught up and translating all incoming changes, getting a specific version translated can be a problem if we set the PR interval to multiple days (and we might want to do that if it turns out that daily is too often). For example if we set it to a PR per week, and a compiler release happens in the middle of the week, there will be no PR containing only changes up to the release. There will be one covering the whole week, possibly containing bits from both versions.

For this reason the bot should:

• Check if a new release has been tagged and if so, issue an additional tag PR that includes only changes from that version. It should still issue a normal periodic PR too.
• We should be able to choose for specific repos to only enable the tag PRs and disable the periodic ones.

The procedure here is close to what I outlined in solidity-docs/id-indonesian#4, but I realized that we can actually do this without even creating fresh repos. By doing it this way, we will keep the original translation branches as a backup and also we'll have less work with configuring the repos:

1. Find the commit in the solidity repo at which the translation started.
   • This needs to be done carefully because if we include commits with text that was not translated, bot will assume it was already translated. On the other hand, if we miss some commits that were translated, the bot will overwrite them with English text in the PR. The latter is easier to spot and correct for the translator so I'd err on the side of going a bit farther into the past if unsure.
2. Clone solidity repository locally and check out the develop branch.
3. Delete everything outside of the docs/ directory and commit.
4. Copy over the translation. There are two ways to do this:
   1. Copy all files (docs/ directory, README, .gitignore and anything else) from the translation repository to the local repo. This is easier and is recommended if there are just a few commits. It will discard translation history though.
      • If there was only one committer in the translation repo, try to preserve his authorship on the new commit (git commit --reedit-message).
   2. Cherry-pick commits from the original translation repo. This will preserve history but is harder because you'll need to resolve conflicts.
5. Rename your local develop to the name of the main branch in the translation repo. Then rename the main branch in the translation repo on github to something else.
6. Add the translation repo a as remote in your local repo (git remote add) and push the main branch to it.

We should try this procedure in the test org first by cloning translation repos. If it goes well, we can later just add the original repos as another remote and push to them.

Hi! I listed all the translations and didn't found ukrainian here. Could we add it? It would be very useful for ukrainian developers and other people.

The Readme needs a section on how translators can translate by version, e.g. in the Solidity documentation, we have one documentation edition per Solidity version. The same should be the case for the translated documentations, so that one can seamlessly switch back and forth between languages of the same page of the same version.

I suggest renaming this repo to Github's special repo .github then README.md file would appear in orgs main page and you can keep docs community files in single repo.

This Github feature allows you to have central place for files e.g Contributing Guidelines, LICENSE, issue templates etc. for all translation org repos.

I have good example of use case in github org which I also provided as example for #8 proposal.

• e.g. org .gihub repo
• in this repo there is profile/README.md which appears then as https://github.com/howijd org page
• you can learn more about .github special repository here https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile

Problem

The Solidity documentation is being translated through community efforts in the solidity-docs organisation. It is hard and overly complicated for the community translators to keep track and catch up with versions and manually update a translation as new Solidity versions get released.

Solution

Automation! Optimally, we would like to have a bot similar to the reactjs-translation-bot, which would create PRs with new content that needs to be translated every time the original documentation is updated.

Task

To semi-automate the process, it would be great if we could set up a bot, similar to the reactjs.org translation bot. The bot creates PRs for new content to be translated from the original English version of the docs. More info on the bot can be found here and this is how a PR from the bot looks like. More context on the process behind the reactjs bot can be found in this issue.

More Details on the Bot Design and Functions

• Set up a bot that creates PRs with diff of newly released docs to translate.
• The solidity/docs developbranch shall be used as a source.
• The PRs should be created in each of the language repositories (currently this means in the repos of the Indonesian, Japanese, Farsi and Portuguese translations).
• The bot should create a PR once per day per language repository.
• The bot should be written in JS, Python or Bash.
• The bot should be part of the solidity-docs GitHub organization and should add PRs to all the different translation repos.
• The bot should use Github Actions as a CI.

Relevant Links

• Official Solidity documentation
• Community translations of documentation

Create a Github Action that monitors all pushes to this repository and automatically creates and sets up a new translation repository whenever a new JSON files is added in langs/.

The action could also update the list of enabled translations in the bot from #12.

The translation bot should tag each PR with a label named after current version in the Solidity repository. This way the translators will be able to easily filter PRs by version.

Currently the bot from #12 has the list of enabled repositories hard-coded in its workflow file. It would be more convenient if it could construct it automatically based on what JSON files are present in langs/.