From b9c9f85aca328f6fc9f98f65570f529503466e15 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sun, 1 Nov 2020 21:45:41 +0100 Subject: [PATCH 01/17] Initial version --- content/recipes/authoring/translation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index d3ba1a2d..ed2ddbd9 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -7,4 +7,4 @@ next: /recipes/authoring/kumite/ # Creating a Translation -_This page is a stub._ \ No newline at end of file +_This page is a stub._ From cf5bd1db888ba365ef4dff490e06c4b6dc81e3f9 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sun, 1 Nov 2020 21:51:55 +0100 Subject: [PATCH 02/17] Initial ideas from discussion --- content/recipes/authoring/translation.md | 26 ++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index ed2ddbd9..3b18e1b7 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -8,3 +8,29 @@ next: /recipes/authoring/kumite/ # Creating a Translation _This page is a stub._ + + +> in unordered fashion: +> +> * make preferably the description language agnostic (if the author is ok with te idea), but if not possible, don't forget to add the relevant codeblocks +> +> wanted changes, compared to the original language: +> +> * adding random tests (required) +> * adding sample tests (required) +> * clarifying the description if needed (only if the author is ok, if he's active) +> * build a better organisation of the test suite +> +> things where you need to "stay in line" +> +> * respect the performances requirements of the original language. If needed decrease/increase the number of tests +> * respect the perf of the original solution +> * respect the overall setup of the initial solution (except for translations "from/to Java/C#" and alike where you adapt to what's the more loical +> * all tests must be translated (unless irrelevant in the translated language) +> +> things to be careful about: (_**these ones will have to be in "create a kata" too**_) +> +> * write readable/maintainable code => golfed ref solutions like Giacommo cas used to do are to be avoided +> * isolate completely ref and user code: when mutable data structures are used as input, either compute the expected result before sending the inputs to the user, or send copies to the user (deep copies if needed) +> * respect the naming conventions of the translated language + From 2d28a91ec021c861abdee4c72f83ebc6b9034039 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Mon, 2 Nov 2020 16:35:11 +0100 Subject: [PATCH 03/17] translation guidelines: initial version --- content/recipes/authoring/translation.md | 69 +++++++++++++++--------- 1 file changed, 43 insertions(+), 26 deletions(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index 3b18e1b7..08bcdfd0 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -7,30 +7,47 @@ next: /recipes/authoring/kumite/ # Creating a Translation -_This page is a stub._ - - -> in unordered fashion: -> -> * make preferably the description language agnostic (if the author is ok with te idea), but if not possible, don't forget to add the relevant codeblocks -> -> wanted changes, compared to the original language: -> -> * adding random tests (required) -> * adding sample tests (required) -> * clarifying the description if needed (only if the author is ok, if he's active) -> * build a better organisation of the test suite -> -> things where you need to "stay in line" -> -> * respect the performances requirements of the original language. If needed decrease/increase the number of tests -> * respect the perf of the original solution -> * respect the overall setup of the initial solution (except for translations "from/to Java/C#" and alike where you adapt to what's the more loical -> * all tests must be translated (unless irrelevant in the translated language) -> -> things to be careful about: (_**these ones will have to be in "create a kata" too**_) -> -> * write readable/maintainable code => golfed ref solutions like Giacommo cas used to do are to be avoided -> * isolate completely ref and user code: when mutable data structures are used as input, either compute the expected result before sending the inputs to the user, or send copies to the user (deep copies if needed) -> * respect the naming conventions of the translated language +This article contains a set of guidelines, which can be used by translators to create good translations to existing kata. They were collected to help ensure that translations are of sufficient quality and users' experience will be as good as possible. +The guidelines should be used by translators and reviewers to verify whether translation which is about to be introduced into Codewars is of sufficient quality. Conformance with them should be verified before the translation is published, and before it's approved. + +Failing to comply with the below guidelines should be reported as an issue or a comment requesting for a fix. In case of severe violations, affected translation can be rejected, or even deleted. + +## General translation guidelines + +- **Respect [General Content Guidelines](/recipes/authoring/general/).** +- **Translations should improve the overall quality of the kata.**. Sub-optimal quality of existing, approved translations should not be used as an argument for low quality of the translation. In particular: + - Description can be clarified, if necessary. + - Test suite can use different structure than other translations. **[Random tests](/recipes/authoring/kata-snippets/full-tests/#random-tests), [full test suite](/recipes/authoring/kata-snippets/full-tests/) and [sample tests](/recipes/authoring/kata-snippets/sample-tests/) should conform to Codewars quality guidelines.** +- If, while translation is created, some serious problems are spotted in other language versions, they should be fixed or raised as appropriate issues in the kata discourse. + + +## Conformance to overall kata idea + +Translation should not substantially change overall idea of the kata. It should be as consistent as possible with the original version in terms of difficulty, required performance, and overall composition. In particular: + +- **Respect the performance requirements of the kata.** If, for example, it's agreed that kata should accept only (sub)linear solutions, make sure that translated tests reject solutions of higher computational complexity. Languages and runtimes differ in terms of performance, so increase/decrease amount of test cases and input ranges when necessary. +- If possible, your translation should hold to **original author's idea**. In case of doubts, you can always ask them for opinion, or use initial language version as a baseline. However, especially for older kata, it may happen that initial version (and other older versions) are outdated, and concept of the kata evolved. You can ask kata contributors or other users for opinion and ideas how to proceed. +- **Avoid translations to languages which cannot support the idea of the kata.** For example, there's no use in translating a big integer arithmetic kata to Python, which supports arbitrary precision integers natively. Do not translate kata into languages where difficulty would signifficantly differ: from high level languages to NASM or BF, or into lnaguages where kata can be solved with easy to use, advanced features of standard library (or other available libraries). + + +## Description + +- **Respect guidelines for [Writing a Kata Description](/recipes/authoring/kata-snippets/description/).** +- **Use [Codewars Markdown Extensions](/references/markdown/extensions/#sequential-code-blocks)** to organize language specific parts of description, if present. Add sections specific to your language if necessary. +- If possible, **avoid displaying many language variants to the user**. Use conditional paragraphs to display information revelant to the currently viewed language. +- If the language version can pass tests successfuly only when run with some specific language runtime, it should be specified in the description. + + +## Code components + +- **Respect [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), coding guidelines of your [language](/languages/), and guidelines specific for particular kata code components ([sample tests](/recipes/authoring/kata-snippets/sample-tests/), [full test suite](/recipes/authoring/kata-snippets/full-tests/), [preloaded code](/recipes/authoring/kata-snippets/preloaded/) and [proposed solution](/recipes/authoring/kata-snippets/proposed-solution/)). +- If possible, **sample tests and fixed tests should use the same inputs in all translations.** It's not always possible between languages, but when done, it makes support of users much easier. When a question about failed test pops up in kata discourse, it can save follow-up questions for attempted language, etc. + + +## Review process + +- **Translation must be reviewed before it's approved.** If reviewer is not familiar with the language of the translation, they should ask other users for help. +- **Any issues found during review should be posted** as translation comments. +- Unfortunately, approval of translation cannot be easily blocked by raising issues. If translation has many issues, cannot be easily fixed, and there's justified concern that it could be approved prematurely while not keeping up to quality standards, **it should be rejected**. +- After translation is approved, it becomes **responsibility of all the parties: the approver, the translator, and the kata author** (in this order) to fix any potential issues which might come up later, when users attempt to submit their solutions. \ No newline at end of file From 1a0a4a66d2ea29532297a5631820713055fbbdcd Mon Sep 17 00:00:00 2001 From: hobovsky Date: Mon, 2 Nov 2020 16:47:26 +0100 Subject: [PATCH 04/17] Fixes for markup --- content/recipes/authoring/translation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index 08bcdfd0..f28c3abf 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -16,7 +16,7 @@ Failing to comply with the below guidelines should be reported as an issue or a ## General translation guidelines - **Respect [General Content Guidelines](/recipes/authoring/general/).** -- **Translations should improve the overall quality of the kata.**. Sub-optimal quality of existing, approved translations should not be used as an argument for low quality of the translation. In particular: +- **Translations should improve the overall quality of the kata.** Sub-optimal quality of existing, approved translations should not be used as an argument for low quality of the translation. In particular: - Description can be clarified, if necessary. - Test suite can use different structure than other translations. **[Random tests](/recipes/authoring/kata-snippets/full-tests/#random-tests), [full test suite](/recipes/authoring/kata-snippets/full-tests/) and [sample tests](/recipes/authoring/kata-snippets/sample-tests/) should conform to Codewars quality guidelines.** - If, while translation is created, some serious problems are spotted in other language versions, they should be fixed or raised as appropriate issues in the kata discourse. @@ -41,7 +41,7 @@ Translation should not substantially change overall idea of the kata. It should ## Code components -- **Respect [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), coding guidelines of your [language](/languages/), and guidelines specific for particular kata code components ([sample tests](/recipes/authoring/kata-snippets/sample-tests/), [full test suite](/recipes/authoring/kata-snippets/full-tests/), [preloaded code](/recipes/authoring/kata-snippets/preloaded/) and [proposed solution](/recipes/authoring/kata-snippets/proposed-solution/)). +- **Respect [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), coding guidelines of your [language](/languages/), and guidelines specific for particular kata code components** ([sample tests](/recipes/authoring/kata-snippets/sample-tests/), [full test suite](/recipes/authoring/kata-snippets/full-tests/), [preloaded code](/recipes/authoring/kata-snippets/preloaded/) and [proposed solution](/recipes/authoring/kata-snippets/proposed-solution/)). - If possible, **sample tests and fixed tests should use the same inputs in all translations.** It's not always possible between languages, but when done, it makes support of users much easier. When a question about failed test pops up in kata discourse, it can save follow-up questions for attempted language, etc. From ec8e211a1e22abcf94a08be02de35653e483246c Mon Sep 17 00:00:00 2001 From: hobovsky Date: Tue, 3 Nov 2020 03:42:49 +0100 Subject: [PATCH 05/17] Note on language specific info in solution setup --- content/recipes/authoring/translation.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index f28c3abf..9e2c9247 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -43,6 +43,7 @@ Translation should not substantially change overall idea of the kata. It should - **Respect [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), coding guidelines of your [language](/languages/), and guidelines specific for particular kata code components** ([sample tests](/recipes/authoring/kata-snippets/sample-tests/), [full test suite](/recipes/authoring/kata-snippets/full-tests/), [preloaded code](/recipes/authoring/kata-snippets/preloaded/) and [proposed solution](/recipes/authoring/kata-snippets/proposed-solution/)). - If possible, **sample tests and fixed tests should use the same inputs in all translations.** It's not always possible between languages, but when done, it makes support of users much easier. When a question about failed test pops up in kata discourse, it can save follow-up questions for attempted language, etc. +- Sometimes, description is not the best place to put some language specific information. For example, translator wants to add some information on arguments, data formats, memory management, etc. and keep the description language-agnostic at the same time. In such cases, it's allowed to put such information as an explanatory comment in "solution setup" snippet. ## Review process @@ -50,4 +51,4 @@ Translation should not substantially change overall idea of the kata. It should - **Translation must be reviewed before it's approved.** If reviewer is not familiar with the language of the translation, they should ask other users for help. - **Any issues found during review should be posted** as translation comments. - Unfortunately, approval of translation cannot be easily blocked by raising issues. If translation has many issues, cannot be easily fixed, and there's justified concern that it could be approved prematurely while not keeping up to quality standards, **it should be rejected**. -- After translation is approved, it becomes **responsibility of all the parties: the approver, the translator, and the kata author** (in this order) to fix any potential issues which might come up later, when users attempt to submit their solutions. \ No newline at end of file +- After translation is approved, it becomes **responsibility of all the parties: the approver, the translator, and the kata author** (in this order) to fix any potential issues which might come up later, when users attempt to submit their solutions. From b7812187a26e3a6cd42dad7407cad75e8d4de0e6 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Tue, 3 Nov 2020 04:13:21 +0100 Subject: [PATCH 06/17] Apply suggestions from code review Co-authored-by: Donald Sebastian Leung --- content/recipes/authoring/translation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index 9e2c9247..000a9072 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -15,11 +15,11 @@ Failing to comply with the below guidelines should be reported as an issue or a ## General translation guidelines -- **Respect [General Content Guidelines](/recipes/authoring/general/).** -- **Translations should improve the overall quality of the kata.** Sub-optimal quality of existing, approved translations should not be used as an argument for low quality of the translation. In particular: - - Description can be clarified, if necessary. +- **Respect the [General Content Guidelines](/recipes/authoring/general/).** +- **Translations should improve the overall quality of the kata.** The sub-optimal quality of existing, approved translations should not be used as an excuse for authoring a low-quality translation. In particular: +- The description can be clarified if necessary. - Test suite can use different structure than other translations. **[Random tests](/recipes/authoring/kata-snippets/full-tests/#random-tests), [full test suite](/recipes/authoring/kata-snippets/full-tests/) and [sample tests](/recipes/authoring/kata-snippets/sample-tests/) should conform to Codewars quality guidelines.** -- If, while translation is created, some serious problems are spotted in other language versions, they should be fixed or raised as appropriate issues in the kata discourse. +- If serious issues with other language versions are uncovered in the course of authoring a translation, they should be fixed or raised as appropriate issues in the kata discourse. ## Conformance to overall kata idea @@ -42,7 +42,7 @@ Translation should not substantially change overall idea of the kata. It should ## Code components - **Respect [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), coding guidelines of your [language](/languages/), and guidelines specific for particular kata code components** ([sample tests](/recipes/authoring/kata-snippets/sample-tests/), [full test suite](/recipes/authoring/kata-snippets/full-tests/), [preloaded code](/recipes/authoring/kata-snippets/preloaded/) and [proposed solution](/recipes/authoring/kata-snippets/proposed-solution/)). -- If possible, **sample tests and fixed tests should use the same inputs in all translations.** It's not always possible between languages, but when done, it makes support of users much easier. When a question about failed test pops up in kata discourse, it can save follow-up questions for attempted language, etc. +- If possible, **sample tests and fixed tests should remain consistent between translations.** It may not always be feasible due to inherent differences in programming languages, but doing so can save follow-up questions on the language a user is attempting the kata in when a question on failing tests is raised in the kata discourse. - Sometimes, description is not the best place to put some language specific information. For example, translator wants to add some information on arguments, data formats, memory management, etc. and keep the description language-agnostic at the same time. In such cases, it's allowed to put such information as an explanatory comment in "solution setup" snippet. From 74d4a0afda6e070c706effc47179ac3a28ae74ed Mon Sep 17 00:00:00 2001 From: Donald Sebastian Leung Date: Wed, 4 Nov 2020 12:07:15 +0800 Subject: [PATCH 07/17] Apply suggestions from code review Co-authored-by: kazk --- content/recipes/authoring/translation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index 000a9072..d5b87d74 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -17,8 +17,8 @@ Failing to comply with the below guidelines should be reported as an issue or a - **Respect the [General Content Guidelines](/recipes/authoring/general/).** - **Translations should improve the overall quality of the kata.** The sub-optimal quality of existing, approved translations should not be used as an excuse for authoring a low-quality translation. In particular: -- The description can be clarified if necessary. - - Test suite can use different structure than other translations. **[Random tests](/recipes/authoring/kata-snippets/full-tests/#random-tests), [full test suite](/recipes/authoring/kata-snippets/full-tests/) and [sample tests](/recipes/authoring/kata-snippets/sample-tests/) should conform to Codewars quality guidelines.** + - The description can be clarified if necessary. +- The test suite may employ a different structure from that of other translations. **The [sample](/recipes/authoring/kata-snippets/sample-tests/) and [submit](/recipes/authoring/kata-snippets/full-tests/) tests (including [random tests](/recipes/authoring/kata-snippets/full-tests/#random-tests)) should conform to Codewars quality guidelines.** - If serious issues with other language versions are uncovered in the course of authoring a translation, they should be fixed or raised as appropriate issues in the kata discourse. @@ -41,7 +41,7 @@ Translation should not substantially change overall idea of the kata. It should ## Code components -- **Respect [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), coding guidelines of your [language](/languages/), and guidelines specific for particular kata code components** ([sample tests](/recipes/authoring/kata-snippets/sample-tests/), [full test suite](/recipes/authoring/kata-snippets/full-tests/), [preloaded code](/recipes/authoring/kata-snippets/preloaded/) and [proposed solution](/recipes/authoring/kata-snippets/proposed-solution/)). +- **Respect the [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), any conventions imposed by your [language](/languages/) and guidelines specific to each component of the kata**, e.g. the [preloaded](/recipes/authoring/kata-snippets/preloaded/) section, [complete solution](/recipes/authoring/kata-snippets/proposed-solution/), [sample tests](/recipes/authoring/kata-snippets/sample-tests/) and [submit tests](/recipes/authoring/kata-snippets/full-tests/). - If possible, **sample tests and fixed tests should remain consistent between translations.** It may not always be feasible due to inherent differences in programming languages, but doing so can save follow-up questions on the language a user is attempting the kata in when a question on failing tests is raised in the kata discourse. - Sometimes, description is not the best place to put some language specific information. For example, translator wants to add some information on arguments, data formats, memory management, etc. and keep the description language-agnostic at the same time. In such cases, it's allowed to put such information as an explanatory comment in "solution setup" snippet. From 72d4d46ece3c3e38382afd546ff3b0285b08bc18 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Wed, 4 Nov 2020 10:05:31 +0100 Subject: [PATCH 08/17] Apply suggestions from code review Co-authored-by: Donald Sebastian Leung --- content/recipes/authoring/translation.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index d5b87d74..b67e74fd 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -9,7 +9,7 @@ next: /recipes/authoring/kumite/ This article contains a set of guidelines, which can be used by translators to create good translations to existing kata. They were collected to help ensure that translations are of sufficient quality and users' experience will be as good as possible. -The guidelines should be used by translators and reviewers to verify whether translation which is about to be introduced into Codewars is of sufficient quality. Conformance with them should be verified before the translation is published, and before it's approved. +The guidelines should be used by translators and reviewers to verify whether translations about to be introduced into Codewars are of sufficient quality. Conformance with them should be verified before the translation is published and before it's approved. Failing to comply with the below guidelines should be reported as an issue or a comment requesting for a fix. In case of severe violations, affected translation can be rejected, or even deleted. @@ -24,17 +24,17 @@ Failing to comply with the below guidelines should be reported as an issue or a ## Conformance to overall kata idea -Translation should not substantially change overall idea of the kata. It should be as consistent as possible with the original version in terms of difficulty, required performance, and overall composition. In particular: +A translation should not substantially change the overall idea of the kata. It should be as consistent as possible with the original version in terms of difficulty, required performance, and overall composition. In particular: - **Respect the performance requirements of the kata.** If, for example, it's agreed that kata should accept only (sub)linear solutions, make sure that translated tests reject solutions of higher computational complexity. Languages and runtimes differ in terms of performance, so increase/decrease amount of test cases and input ranges when necessary. -- If possible, your translation should hold to **original author's idea**. In case of doubts, you can always ask them for opinion, or use initial language version as a baseline. However, especially for older kata, it may happen that initial version (and other older versions) are outdated, and concept of the kata evolved. You can ask kata contributors or other users for opinion and ideas how to proceed. -- **Avoid translations to languages which cannot support the idea of the kata.** For example, there's no use in translating a big integer arithmetic kata to Python, which supports arbitrary precision integers natively. Do not translate kata into languages where difficulty would signifficantly differ: from high level languages to NASM or BF, or into lnaguages where kata can be solved with easy to use, advanced features of standard library (or other available libraries). +- If possible, your translation should hold to the **original author's idea**. In case of doubts, you can always ask them for opinions, or use the initial language version as a baseline. However, especially for older kata, it may happen that the initial version (and other older versions) are outdated, and the concept of the kata evolved. You can ask kata contributors or other users for opinion and ideas on how to proceed. +- **Avoid translations to languages which cannot support the idea of the kata.** For example, there's no use in translating a big integer arithmetic kata to Python, which supports arbitrary precision integers natively. Do not translate kata into languages where the difficulty would significantly differ: from high level languages to NASM or BF, or into languages where the kata can be solved with easy to use, advanced features of the standard library (or other available libraries). ## Description - **Respect guidelines for [Writing a Kata Description](/recipes/authoring/kata-snippets/description/).** -- **Use [Codewars Markdown Extensions](/references/markdown/extensions/#sequential-code-blocks)** to organize language specific parts of description, if present. Add sections specific to your language if necessary. +- **Use [Codewars Markdown Extensions](/references/markdown/extensions/#sequential-code-blocks)** to organize language specific parts of the description, if present. Add sections specific to your language if necessary. - If possible, **avoid displaying many language variants to the user**. Use conditional paragraphs to display information revelant to the currently viewed language. - If the language version can pass tests successfuly only when run with some specific language runtime, it should be specified in the description. @@ -43,12 +43,12 @@ Translation should not substantially change overall idea of the kata. It should - **Respect the [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), any conventions imposed by your [language](/languages/) and guidelines specific to each component of the kata**, e.g. the [preloaded](/recipes/authoring/kata-snippets/preloaded/) section, [complete solution](/recipes/authoring/kata-snippets/proposed-solution/), [sample tests](/recipes/authoring/kata-snippets/sample-tests/) and [submit tests](/recipes/authoring/kata-snippets/full-tests/). - If possible, **sample tests and fixed tests should remain consistent between translations.** It may not always be feasible due to inherent differences in programming languages, but doing so can save follow-up questions on the language a user is attempting the kata in when a question on failing tests is raised in the kata discourse. -- Sometimes, description is not the best place to put some language specific information. For example, translator wants to add some information on arguments, data formats, memory management, etc. and keep the description language-agnostic at the same time. In such cases, it's allowed to put such information as an explanatory comment in "solution setup" snippet. +- Sometimes, the description is not the best place to put some language specific information. For example, the translator may wish to add some information on arguments, data formats, memory management, etc. and keep the description language-agnostic at the same time. In such cases, it's allowed to put such information as an explanatory comments in the solution setup. ## Review process -- **Translation must be reviewed before it's approved.** If reviewer is not familiar with the language of the translation, they should ask other users for help. +- **The translation must be reviewed before it's approved.** If the reviewer is not familiar with the language of the translation, they should ask other users for help. - **Any issues found during review should be posted** as translation comments. -- Unfortunately, approval of translation cannot be easily blocked by raising issues. If translation has many issues, cannot be easily fixed, and there's justified concern that it could be approved prematurely while not keeping up to quality standards, **it should be rejected**. -- After translation is approved, it becomes **responsibility of all the parties: the approver, the translator, and the kata author** (in this order) to fix any potential issues which might come up later, when users attempt to submit their solutions. +- Unfortunately, the approval of a translation cannot be easily blocked by raising issues. If a translation has many issues, cannot be easily fixed, and there's justified concern that it could be approved prematurely while not keeping up to quality standards, **it should be rejected**. +- After a translation is approved, it becomes **the responsibility of all parties involved: the user who approved the translation, the translator, and the kata author** (in this order) to fix any potential issues which might come up later when users attempt to submit their solutions. From a1f209512d70d8fb16a027a40d535ed8dcd80d04 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Wed, 4 Nov 2020 11:32:48 +0100 Subject: [PATCH 09/17] Apply suggestions from code review Co-authored-by: Donald Sebastian Leung --- content/recipes/authoring/translation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index b67e74fd..e0f6a56b 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -11,7 +11,7 @@ This article contains a set of guidelines, which can be used by translators to c The guidelines should be used by translators and reviewers to verify whether translations about to be introduced into Codewars are of sufficient quality. Conformance with them should be verified before the translation is published and before it's approved. -Failing to comply with the below guidelines should be reported as an issue or a comment requesting for a fix. In case of severe violations, affected translation can be rejected, or even deleted. +Failure to comply with the below guidelines is considered an issue and should be reported as such. In case of severe violations, the affected translation can be rejected or even deleted. ## General translation guidelines @@ -26,7 +26,7 @@ Failing to comply with the below guidelines should be reported as an issue or a A translation should not substantially change the overall idea of the kata. It should be as consistent as possible with the original version in terms of difficulty, required performance, and overall composition. In particular: -- **Respect the performance requirements of the kata.** If, for example, it's agreed that kata should accept only (sub)linear solutions, make sure that translated tests reject solutions of higher computational complexity. Languages and runtimes differ in terms of performance, so increase/decrease amount of test cases and input ranges when necessary. +- **Respect the performance requirements of the kata.** If, for example, it's agreed that the kata should accept only (sub)linear solutions, make sure that the translated tests reject solutions of higher computational complexity. Languages and runtimes differ in terms of performance, so increase/decrease the amount of test cases and input ranges accordingly. - If possible, your translation should hold to the **original author's idea**. In case of doubts, you can always ask them for opinions, or use the initial language version as a baseline. However, especially for older kata, it may happen that the initial version (and other older versions) are outdated, and the concept of the kata evolved. You can ask kata contributors or other users for opinion and ideas on how to proceed. - **Avoid translations to languages which cannot support the idea of the kata.** For example, there's no use in translating a big integer arithmetic kata to Python, which supports arbitrary precision integers natively. Do not translate kata into languages where the difficulty would significantly differ: from high level languages to NASM or BF, or into languages where the kata can be solved with easy to use, advanced features of the standard library (or other available libraries). From 504a8bedfda18c171917e7f81a2eb9029b71be50 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Wed, 4 Nov 2020 15:53:36 +0100 Subject: [PATCH 10/17] fix names for code snippets --- content/recipes/authoring/translation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index e0f6a56b..a23a8648 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -18,7 +18,7 @@ Failure to comply with the below guidelines is considered an issue and should be - **Respect the [General Content Guidelines](/recipes/authoring/general/).** - **Translations should improve the overall quality of the kata.** The sub-optimal quality of existing, approved translations should not be used as an excuse for authoring a low-quality translation. In particular: - The description can be clarified if necessary. -- The test suite may employ a different structure from that of other translations. **The [sample](/recipes/authoring/kata-snippets/sample-tests/) and [submit](/recipes/authoring/kata-snippets/full-tests/) tests (including [random tests](/recipes/authoring/kata-snippets/full-tests/#random-tests)) should conform to Codewars quality guidelines.** +- The test suite may employ a different structure from that of other translations. **The [sample](/recipes/authoring/kata-snippets/sample-tests/) and [submission](/recipes/authoring/kata-snippets/full-tests/) tests (including [random tests](/recipes/authoring/kata-snippets/full-tests/#random-tests)) should conform to Codewars quality guidelines.** - If serious issues with other language versions are uncovered in the course of authoring a translation, they should be fixed or raised as appropriate issues in the kata discourse. @@ -41,7 +41,7 @@ A translation should not substantially change the overall idea of the kata. It s ## Code components -- **Respect the [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), any conventions imposed by your [language](/languages/) and guidelines specific to each component of the kata**, e.g. the [preloaded](/recipes/authoring/kata-snippets/preloaded/) section, [complete solution](/recipes/authoring/kata-snippets/proposed-solution/), [sample tests](/recipes/authoring/kata-snippets/sample-tests/) and [submit tests](/recipes/authoring/kata-snippets/full-tests/). +- **Respect the [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), any conventions imposed by your [language](/languages/) and guidelines specific to each component of the kata**, e.g. the [preloaded](/recipes/authoring/kata-snippets/preloaded/) section, [reference solution](/recipes/authoring/kata-snippets/reference-solution/), [sample tests](/recipes/authoring/kata-snippets/sample-tests/) and [submission tests](/recipes/authoring/kata-snippets/full-tests/). - If possible, **sample tests and fixed tests should remain consistent between translations.** It may not always be feasible due to inherent differences in programming languages, but doing so can save follow-up questions on the language a user is attempting the kata in when a question on failing tests is raised in the kata discourse. - Sometimes, the description is not the best place to put some language specific information. For example, the translator may wish to add some information on arguments, data formats, memory management, etc. and keep the description language-agnostic at the same time. In such cases, it's allowed to put such information as an explanatory comments in the solution setup. From fcdd9af86e7a8fb2d58da27e167c59b2c37712e8 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Thu, 5 Nov 2020 03:26:27 +0100 Subject: [PATCH 11/17] Apply suggestions from code review Co-authored-by: Donald Sebastian Leung --- content/recipes/authoring/translation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index a23a8648..0e99e0aa 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -43,7 +43,7 @@ A translation should not substantially change the overall idea of the kata. It s - **Respect the [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), any conventions imposed by your [language](/languages/) and guidelines specific to each component of the kata**, e.g. the [preloaded](/recipes/authoring/kata-snippets/preloaded/) section, [reference solution](/recipes/authoring/kata-snippets/reference-solution/), [sample tests](/recipes/authoring/kata-snippets/sample-tests/) and [submission tests](/recipes/authoring/kata-snippets/full-tests/). - If possible, **sample tests and fixed tests should remain consistent between translations.** It may not always be feasible due to inherent differences in programming languages, but doing so can save follow-up questions on the language a user is attempting the kata in when a question on failing tests is raised in the kata discourse. -- Sometimes, the description is not the best place to put some language specific information. For example, the translator may wish to add some information on arguments, data formats, memory management, etc. and keep the description language-agnostic at the same time. In such cases, it's allowed to put such information as an explanatory comments in the solution setup. +- Sometimes, the description is not the best place to put some language specific information. For example, the translator may wish to add some information on arguments, data formats, memory management, etc. and keep the description language-agnostic at the same time. In such cases, it's allowed to put such information as an explanatory comment in the solution setup. ## Review process From b080aa5917a0df52d674e63648b8f71cec40d45c Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sun, 8 Nov 2020 02:23:36 +0100 Subject: [PATCH 12/17] Formatting --- content/recipes/authoring/translation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index 0e99e0aa..fa4aac3c 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -18,8 +18,8 @@ Failure to comply with the below guidelines is considered an issue and should be - **Respect the [General Content Guidelines](/recipes/authoring/general/).** - **Translations should improve the overall quality of the kata.** The sub-optimal quality of existing, approved translations should not be used as an excuse for authoring a low-quality translation. In particular: - The description can be clarified if necessary. -- The test suite may employ a different structure from that of other translations. **The [sample](/recipes/authoring/kata-snippets/sample-tests/) and [submission](/recipes/authoring/kata-snippets/full-tests/) tests (including [random tests](/recipes/authoring/kata-snippets/full-tests/#random-tests)) should conform to Codewars quality guidelines.** -- If serious issues with other language versions are uncovered in the course of authoring a translation, they should be fixed or raised as appropriate issues in the kata discourse. + - The test suite may employ a different structure from that of other translations. **The [sample](/recipes/authoring/kata-snippets/sample-tests/) and [submission](/recipes/authoring/kata-snippets/full-tests/) tests (including [random tests](/recipes/authoring/kata-snippets/full-tests/#random-tests)) should conform to Codewars quality guidelines.** + - If serious issues with other language versions are uncovered in the course of authoring a translation, they should be fixed or raised as appropriate issues in the kata discourse. ## Conformance to overall kata idea From ff127229898993edf3fa50e1e24edda8cfd18d38 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Sun, 8 Nov 2020 02:30:54 +0100 Subject: [PATCH 13/17] Do not translate into easier languages --- content/recipes/authoring/translation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index fa4aac3c..7a68d953 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -28,7 +28,7 @@ A translation should not substantially change the overall idea of the kata. It s - **Respect the performance requirements of the kata.** If, for example, it's agreed that the kata should accept only (sub)linear solutions, make sure that the translated tests reject solutions of higher computational complexity. Languages and runtimes differ in terms of performance, so increase/decrease the amount of test cases and input ranges accordingly. - If possible, your translation should hold to the **original author's idea**. In case of doubts, you can always ask them for opinions, or use the initial language version as a baseline. However, especially for older kata, it may happen that the initial version (and other older versions) are outdated, and the concept of the kata evolved. You can ask kata contributors or other users for opinion and ideas on how to proceed. -- **Avoid translations to languages which cannot support the idea of the kata.** For example, there's no use in translating a big integer arithmetic kata to Python, which supports arbitrary precision integers natively. Do not translate kata into languages where the difficulty would significantly differ: from high level languages to NASM or BF, or into languages where the kata can be solved with easy to use, advanced features of the standard library (or other available libraries). +- **Avoid translations to languages which cannot support the idea of the kata.** For example, there's no use in translating a big integer arithmetic kata to Python, which supports arbitrary precision integers natively. Do not translate kata into languages where the difficulty would significantly differ: from high level languages to NASM or BF, or into languages where the kata becomes much easier because it can be solved with easy to use, advanced features of the standard library (or other available libraries). ## Description From 16f9d0903d5b9374add1db020e2011398c284704 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Mon, 9 Nov 2020 23:50:39 +0100 Subject: [PATCH 14/17] Apply suggestions from code review --- content/recipes/authoring/translation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index 7a68d953..573ec305 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -22,7 +22,7 @@ Failure to comply with the below guidelines is considered an issue and should be - If serious issues with other language versions are uncovered in the course of authoring a translation, they should be fixed or raised as appropriate issues in the kata discourse. -## Conformance to overall kata idea +## Conformity to overall kata idea A translation should not substantially change the overall idea of the kata. It should be as consistent as possible with the original version in terms of difficulty, required performance, and overall composition. In particular: From 49a520c6e94ec99a1a907faa5373368a656e8685 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Wed, 11 Nov 2020 01:37:39 +0100 Subject: [PATCH 15/17] Organization of bullet points with links --- content/recipes/authoring/translation.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index 573ec305..e70f369f 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -41,7 +41,11 @@ A translation should not substantially change the overall idea of the kata. It s ## Code components -- **Respect the [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), any conventions imposed by your [language](/languages/) and guidelines specific to each component of the kata**, e.g. the [preloaded](/recipes/authoring/kata-snippets/preloaded/) section, [reference solution](/recipes/authoring/kata-snippets/reference-solution/), [sample tests](/recipes/authoring/kata-snippets/sample-tests/) and [submission tests](/recipes/authoring/kata-snippets/full-tests/). +- **Respect the [General Coding Guidelines](/recipes/authoring/kata-snippets/coding-general/), any conventions imposed by your [language](/languages/) and guidelines specific to each component of the kata**: + - [preloaded code](/recipes/authoring/kata-snippets/preloaded/), + - [reference solution](/recipes/authoring/kata-snippets/reference-solution/), + - [sample tests](/recipes/authoring/kata-snippets/sample-tests/), + - [submission tests](/recipes/authoring/kata-snippets/full-tests/). - If possible, **sample tests and fixed tests should remain consistent between translations.** It may not always be feasible due to inherent differences in programming languages, but doing so can save follow-up questions on the language a user is attempting the kata in when a question on failing tests is raised in the kata discourse. - Sometimes, the description is not the best place to put some language specific information. For example, the translator may wish to add some information on arguments, data formats, memory management, etc. and keep the description language-agnostic at the same time. In such cases, it's allowed to put such information as an explanatory comment in the solution setup. From ef8014903236c440efc9cb3e4d08ef3f976c79e2 Mon Sep 17 00:00:00 2001 From: hobovsky Date: Wed, 11 Nov 2020 04:01:09 +0100 Subject: [PATCH 16/17] Apply suggestions from code review Co-authored-by: Blind4Basics <32236948+Blind4Basics@users.noreply.github.com> --- content/recipes/authoring/translation.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index e70f369f..79ef6854 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -19,12 +19,12 @@ Failure to comply with the below guidelines is considered an issue and should be - **Translations should improve the overall quality of the kata.** The sub-optimal quality of existing, approved translations should not be used as an excuse for authoring a low-quality translation. In particular: - The description can be clarified if necessary. - The test suite may employ a different structure from that of other translations. **The [sample](/recipes/authoring/kata-snippets/sample-tests/) and [submission](/recipes/authoring/kata-snippets/full-tests/) tests (including [random tests](/recipes/authoring/kata-snippets/full-tests/#random-tests)) should conform to Codewars quality guidelines.** - - If serious issues with other language versions are uncovered in the course of authoring a translation, they should be fixed or raised as appropriate issues in the kata discourse. + - If serious issues with other language versions are uncovered while translating, they should be fixed in the translation and appropriate issues should be raised about all other concerned languages in the kata discourse. ## Conformity to overall kata idea -A translation should not substantially change the overall idea of the kata. It should be as consistent as possible with the original version in terms of difficulty, required performance, and overall composition. In particular: +A translation should not substantially change either the overall idea nor the requirements of the kata. It should be as consistent as possible with the original version in terms of difficulty, required performance, and overall composition. In particular: - **Respect the performance requirements of the kata.** If, for example, it's agreed that the kata should accept only (sub)linear solutions, make sure that the translated tests reject solutions of higher computational complexity. Languages and runtimes differ in terms of performance, so increase/decrease the amount of test cases and input ranges accordingly. - If possible, your translation should hold to the **original author's idea**. In case of doubts, you can always ask them for opinions, or use the initial language version as a baseline. However, especially for older kata, it may happen that the initial version (and other older versions) are outdated, and the concept of the kata evolved. You can ask kata contributors or other users for opinion and ideas on how to proceed. @@ -35,8 +35,8 @@ A translation should not substantially change the overall idea of the kata. It s - **Respect guidelines for [Writing a Kata Description](/recipes/authoring/kata-snippets/description/).** - **Use [Codewars Markdown Extensions](/references/markdown/extensions/#sequential-code-blocks)** to organize language specific parts of the description, if present. Add sections specific to your language if necessary. -- If possible, **avoid displaying many language variants to the user**. Use conditional paragraphs to display information revelant to the currently viewed language. -- If the language version can pass tests successfuly only when run with some specific language runtime, it should be specified in the description. +- If possible, **avoid displaying many language variants to the user**. Use [conditional paragraphs](references/markdown/extensions/#conditional-rendering) to display information revelant to the currently viewed language. +- If a translation can pass tests only when run with some specific language runtime, it should be specified in the description. ## Code components @@ -46,13 +46,13 @@ A translation should not substantially change the overall idea of the kata. It s - [reference solution](/recipes/authoring/kata-snippets/reference-solution/), - [sample tests](/recipes/authoring/kata-snippets/sample-tests/), - [submission tests](/recipes/authoring/kata-snippets/full-tests/). -- If possible, **sample tests and fixed tests should remain consistent between translations.** It may not always be feasible due to inherent differences in programming languages, but doing so can save follow-up questions on the language a user is attempting the kata in when a question on failing tests is raised in the kata discourse. +- **Sample tests and fixed tests should remain consistent between translations**, except in some rare cases when it's not feasible due to inherent differences in programming languages. It can save follow-up questions on the language a user is attempting the kata in when a question on failing tests is raised in the kata discourse. - Sometimes, the description is not the best place to put some language specific information. For example, the translator may wish to add some information on arguments, data formats, memory management, etc. and keep the description language-agnostic at the same time. In such cases, it's allowed to put such information as an explanatory comment in the solution setup. ## Review process - **The translation must be reviewed before it's approved.** If the reviewer is not familiar with the language of the translation, they should ask other users for help. -- **Any issues found during review should be posted** as translation comments. -- Unfortunately, the approval of a translation cannot be easily blocked by raising issues. If a translation has many issues, cannot be easily fixed, and there's justified concern that it could be approved prematurely while not keeping up to quality standards, **it should be rejected**. -- After a translation is approved, it becomes **the responsibility of all parties involved: the user who approved the translation, the translator, and the kata author** (in this order) to fix any potential issues which might come up later when users attempt to submit their solutions. +When issues with the translation are found during its review, they should be reported and discussed in the comment section of the translation so that the translator can be notified and handle them. +- If a translation has too many issues or cannot be easily fixed, and there's justified concern that it could be approved prematurely while not keeping up to quality standards, **it can be rejected**. +- After a translation is approved, it becomes **the responsibility of all parties involved: the translator, the user who approved the translation, and the kata author**, to fix any potential issues which might come up later when users attempt to submit their solutions. From d101ade0fa2a851b99809333411a1f17ca91deae Mon Sep 17 00:00:00 2001 From: hobovsky Date: Wed, 11 Nov 2020 04:54:18 +0100 Subject: [PATCH 17/17] Apply suggestions from code review Co-authored-by: Donald Sebastian Leung --- content/recipes/authoring/translation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/recipes/authoring/translation.md b/content/recipes/authoring/translation.md index 79ef6854..00590982 100644 --- a/content/recipes/authoring/translation.md +++ b/content/recipes/authoring/translation.md @@ -24,7 +24,7 @@ Failure to comply with the below guidelines is considered an issue and should be ## Conformity to overall kata idea -A translation should not substantially change either the overall idea nor the requirements of the kata. It should be as consistent as possible with the original version in terms of difficulty, required performance, and overall composition. In particular: +A translation should substantially change neither the overall idea nor the requirements of the kata. It should be as consistent as possible with the original version in terms of difficulty, required performance, and overall composition. In particular: - **Respect the performance requirements of the kata.** If, for example, it's agreed that the kata should accept only (sub)linear solutions, make sure that the translated tests reject solutions of higher computational complexity. Languages and runtimes differ in terms of performance, so increase/decrease the amount of test cases and input ranges accordingly. - If possible, your translation should hold to the **original author's idea**. In case of doubts, you can always ask them for opinions, or use the initial language version as a baseline. However, especially for older kata, it may happen that the initial version (and other older versions) are outdated, and the concept of the kata evolved. You can ask kata contributors or other users for opinion and ideas on how to proceed.