From aba8e51aa78d83c2bf70ed9fab2c21af57a1157b Mon Sep 17 00:00:00 2001 From: chabros Date: Sun, 2 Mar 2025 15:53:20 +0100 Subject: [PATCH 1/6] HOWTO - fixing kata --- content/curation/howtos/fixing.md | 61 +++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 content/curation/howtos/fixing.md diff --git a/content/curation/howtos/fixing.md b/content/curation/howtos/fixing.md new file mode 100644 index 00000000..edb9b40a --- /dev/null +++ b/content/curation/howtos/fixing.md @@ -0,0 +1,61 @@ +--- +title: How to Fix a Kata +--- + +Codewars kata, like any code, may need bug fixing, improvements, or update to match new versions of runtimes or dependencies. That's why content maintenance activities are important and sometimes can require significant amounts of effort. + +## Finding a kata to fix + +First step to fix a Codewars kata is to determine what kata need fixing in the first place. Codewars platform provides a couple of ways to find challenges which require maintenance: + +- On the [kata search page](https://www.codewars.com/kata/my-languages), every entry shows the amount of pending issues (if it has any). +- Posts on the home page [dashboard](https://www.codewars.com/dashboard/discourse/issues) can be filtered to display most recently reported issues, +- Discourse page of every kata can be filtered for posts labeled as `ISSUE`, +- The [kata search page](https://www.codewars.com/kata/) can be used to find challenges which have not been updated to the latest version of their available languages. For example, to find kata with tests which need to be updated to the latest available version of JavaScript, filter for language: Javascript, and manually add the parameter `&outdated=1` to the url (example link to find all [outdated JavaScript kata](https://www.codewars.com/kata/search/javascript?q=&order_by=sort_date%20desc&outdated=1)). +- The [`codewars/content-issues`](https://github.com/codewars/content-issues) Github repository hosts [wiki pages](https://github.com/codewars/content-issues/wiki) with lists of kata which need an update, and [isseue board](https://github.com/codewars/content-issues/issues) with tickets related to maintenance of kata. + +## Creating a fork + +New fork can be initiated by opening kata details page, selecting one of available languages, and clicking the `Fork` button at the top right corner. It opens the fork editor, and all editors are filled with the current state of corresponding code snippets in the selected language, and description. This code can be edited and used as a starting point for a fix. + +:::warning Do not fork outdated forks +Fixes should not be applied by starting with a fork of an already approved fork. For example, when an issue is reported with a JavaScript version of a kata, it should be fixed by forking the current state of the kata, and not by forking the original, approved JavaScript translation, or the most recent JavaScript translation. It is possible that the kata had been modified after the translation was published and approved, and forking an old fork can revert changes applied afterwards. +::: + +:::warning Prefer forks to direct edits +Applying fixes by forks is preferred over updates done with the kata editor. Forks can be reviewed and reviewers can share their remarks before approving the fix. +::: + +### Scope of a fix + +A single Codewars challenge can be affected by more than one problem. It can be tempting to fix as many things as possible in one go, or even rewrite tests completely, but it is not always the best approach. Forks with extensive changes require a lot of effort to create, can be difficult to review, and it is more difficult for reviewers to determine what they attempt to fix and find potential bugs. Forks which are difficult to review can stay not reviewed, and not approved, for a long time. A user has to find a good balance between fixes with large amount of changes attempting to fix many things at once, and fixes with small amount of changes, which are easy to review and approve. Applying a series of small fixes can sometimes be easier than applying one fix for many issues at once. + +It is recommended to write a short post on a published fork with information what problems it addresses. + +### Announcing the fork + +When a fork with a fix is ready, it needs to be published for a review, and potentially merged. To notify reviewers about a fork ready for review, it can be helpful to announce the fix with a message posted in the discourse section of the kata (labeled as `SUGGESTION`), and with a message posted to the `#fixing` channel of Codewars Discord. + +### Review of a fork + +After a fork with a fix is published and announced, it should draw attention of reviewers who will evaluate it and either approve it, or ask for further improvements. + +Users with sufficient privileges can approve their own forks without waiting for a review. + +When a reviewer requests further improvements, they can be added to the same fork. It is not necessary to fork a fork if it hasn't been approved or rejected. However, if the fork has been merged and was found to require further improvements, it needs to be re-forked. Editing an approved fork is possible, but there is no way to merge the new changes into the kata. + +### Resources on fixing + +Users who are interested with fixing Codewars challenges have some resources at their disposal: + +- [Codewars documentation](https://docs.codewars.com/), +- [Authoring examples](https://www.codewars.com/collections/authoring-examples) collection, +- Codewars Discord and its `#fixing` channel. + +### Community resources + +:::info Note +Community resources are created and maintained by Codewars users not affiliated with the platform. These resources are not maintained by Codewars, and can turn out to be outdated or not functional. +::: + +- [Codot](https://github.com/hobovsky/codot-client/blob/main/README.md#fixing-forks-beta) an AI-powered assistant and its [fork refactoring](https://github.com/hobovsky/codot-client/blob/main/README.fixing.md#fixing-forks-with-codot-beta) function. From ca6aad7f8dada8bf0d238904ad904f9674856462 Mon Sep 17 00:00:00 2001 From: chabros Date: Sun, 2 Mar 2025 16:05:47 +0100 Subject: [PATCH 2/6] Fixes for spelling and grammar --- content/curation/howtos/fixing.md | 44 ++++++++++++++++--------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/content/curation/howtos/fixing.md b/content/curation/howtos/fixing.md index edb9b40a..02c89f1e 100644 --- a/content/curation/howtos/fixing.md +++ b/content/curation/howtos/fixing.md @@ -2,60 +2,62 @@ title: How to Fix a Kata --- -Codewars kata, like any code, may need bug fixing, improvements, or update to match new versions of runtimes or dependencies. That's why content maintenance activities are important and sometimes can require significant amounts of effort. +Codewars kata, like any code, may need bug fixes, improvements, or updates to match new versions of runtimes or dependencies. That's why content maintenance activities are important and sometimes require significant effort. ## Finding a kata to fix -First step to fix a Codewars kata is to determine what kata need fixing in the first place. Codewars platform provides a couple of ways to find challenges which require maintenance: +The first step to fixing a Codewars kata is determining which kata need fixing in the first place. The Codewars platform provides several ways to find challenges that require maintenance: -- On the [kata search page](https://www.codewars.com/kata/my-languages), every entry shows the amount of pending issues (if it has any). -- Posts on the home page [dashboard](https://www.codewars.com/dashboard/discourse/issues) can be filtered to display most recently reported issues, -- Discourse page of every kata can be filtered for posts labeled as `ISSUE`, -- The [kata search page](https://www.codewars.com/kata/) can be used to find challenges which have not been updated to the latest version of their available languages. For example, to find kata with tests which need to be updated to the latest available version of JavaScript, filter for language: Javascript, and manually add the parameter `&outdated=1` to the url (example link to find all [outdated JavaScript kata](https://www.codewars.com/kata/search/javascript?q=&order_by=sort_date%20desc&outdated=1)). -- The [`codewars/content-issues`](https://github.com/codewars/content-issues) Github repository hosts [wiki pages](https://github.com/codewars/content-issues/wiki) with lists of kata which need an update, and [isseue board](https://github.com/codewars/content-issues/issues) with tickets related to maintenance of kata. +- On the [kata search page](https://www.codewars.com/kata/my-languages), every entry shows the number of pending issues (if any). +- Posts on the home page [dashboard](https://www.codewars.com/dashboard/discourse/issues) can be filtered to display the most recently reported issues. +- The discourse page of every kata can be filtered for posts labeled as `ISSUE`. +- The [kata search page](https://www.codewars.com/kata/) can be used to find challenges that have not been updated to the latest version of their available languages. For example, to find kata with tests that need to be updated to the latest available version of JavaScript, filter for language: JavaScript, and manually add the parameter `&outdated=1` to the URL (example link to find all [outdated JavaScript kata](https://www.codewars.com/kata/search/javascript?q=&order_by=sort_date%20desc&outdated=1)). +- The [`codewars/content-issues`](https://github.com/codewars/content-issues) GitHub repository hosts [wiki pages](https://github.com/codewars/content-issues/wiki) with lists of kata that need an update and an [issue board](https://github.com/codewars/content-issues/issues) with tickets related to kata maintenance. ## Creating a fork -New fork can be initiated by opening kata details page, selecting one of available languages, and clicking the `Fork` button at the top right corner. It opens the fork editor, and all editors are filled with the current state of corresponding code snippets in the selected language, and description. This code can be edited and used as a starting point for a fix. +A new fork can be initiated by opening the kata details page, selecting one of the available languages, and clicking the `Fork` button at the top right corner. This opens the fork editor, where all editors are populated with the current state of the corresponding code snippets in the selected language and description. This code can be edited and used as a starting point for a fix. :::warning Do not fork outdated forks -Fixes should not be applied by starting with a fork of an already approved fork. For example, when an issue is reported with a JavaScript version of a kata, it should be fixed by forking the current state of the kata, and not by forking the original, approved JavaScript translation, or the most recent JavaScript translation. It is possible that the kata had been modified after the translation was published and approved, and forking an old fork can revert changes applied afterwards. +Fixes should not be applied by starting with a fork of an already approved fork. For example, when an issue is reported with a JavaScript version of a kata, it should be fixed by forking the current state of the kata, not by forking the original, approved JavaScript translation or the most recent JavaScript translation. The kata may have been modified after the translation was published and approved, and forking an old fork can revert changes applied afterward. ::: :::warning Prefer forks to direct edits -Applying fixes by forks is preferred over updates done with the kata editor. Forks can be reviewed and reviewers can share their remarks before approving the fix. +Applying fixes via forks is preferred over updates done with the kata editor. Forks can be reviewed, and reviewers can share their remarks before approving the fix. ::: ### Scope of a fix -A single Codewars challenge can be affected by more than one problem. It can be tempting to fix as many things as possible in one go, or even rewrite tests completely, but it is not always the best approach. Forks with extensive changes require a lot of effort to create, can be difficult to review, and it is more difficult for reviewers to determine what they attempt to fix and find potential bugs. Forks which are difficult to review can stay not reviewed, and not approved, for a long time. A user has to find a good balance between fixes with large amount of changes attempting to fix many things at once, and fixes with small amount of changes, which are easy to review and approve. Applying a series of small fixes can sometimes be easier than applying one fix for many issues at once. +A single Codewars challenge can be affected by multiple problems. It may be tempting to fix as many things as possible in one go or even rewrite tests completely, but this is not always the best approach. Forks with extensive changes require significant effort to create, can be difficult to review, and make it harder for reviewers to determine what they attempt to fix and identify potential bugs. Forks that are difficult to review may remain unreviewed and unapproved for a long time. -It is recommended to write a short post on a published fork with information what problems it addresses. +A user must find a balance between making large-scale fixes that attempt to address many issues at once and smaller, incremental changes that are easier to review and approve. Sometimes, applying a series of small fixes is more effective than attempting to fix multiple issues in a single fork. + +It is recommended to write a short post on a published fork explaining what problems it addresses. ### Announcing the fork -When a fork with a fix is ready, it needs to be published for a review, and potentially merged. To notify reviewers about a fork ready for review, it can be helpful to announce the fix with a message posted in the discourse section of the kata (labeled as `SUGGESTION`), and with a message posted to the `#fixing` channel of Codewars Discord. +When a fork with a fix is ready, it needs to be published for review and potential merging. To notify reviewers about a fork ready for review, it can be helpful to announce the fix with a message posted in the discourse section of the kata (labeled as `SUGGESTION`) and in the `#fixing` channel of the Codewars Discord. ### Review of a fork -After a fork with a fix is published and announced, it should draw attention of reviewers who will evaluate it and either approve it, or ask for further improvements. +After a fork with a fix is published and announced, it should attract the attention of reviewers who will evaluate it and either approve it or request further improvements. Users with sufficient privileges can approve their own forks without waiting for a review. -When a reviewer requests further improvements, they can be added to the same fork. It is not necessary to fork a fork if it hasn't been approved or rejected. However, if the fork has been merged and was found to require further improvements, it needs to be re-forked. Editing an approved fork is possible, but there is no way to merge the new changes into the kata. +When a reviewer requests further improvements, they can be added to the same fork. It is not necessary to fork a fork if it hasn't been approved or rejected. However, if the fork has already been merged and further improvements are required, it must be re-forked. Editing an approved fork is possible, but there is no way to merge the new changes into the kata. ### Resources on fixing -Users who are interested with fixing Codewars challenges have some resources at their disposal: +Users interested in fixing Codewars challenges have several resources at their disposal: -- [Codewars documentation](https://docs.codewars.com/), -- [Authoring examples](https://www.codewars.com/collections/authoring-examples) collection, -- Codewars Discord and its `#fixing` channel. +- [Codewars documentation](https://docs.codewars.com/) +- [Authoring examples](https://www.codewars.com/collections/authoring-examples) collection +- Codewars Discord and its `#fixing` channel ### Community resources :::info Note -Community resources are created and maintained by Codewars users not affiliated with the platform. These resources are not maintained by Codewars, and can turn out to be outdated or not functional. +Community resources are created and maintained by Codewars users not affiliated with the platform. These resources are not maintained by Codewars and may become outdated or non-functional. ::: -- [Codot](https://github.com/hobovsky/codot-client/blob/main/README.md#fixing-forks-beta) an AI-powered assistant and its [fork refactoring](https://github.com/hobovsky/codot-client/blob/main/README.fixing.md#fixing-forks-with-codot-beta) function. +- [Codot](https://github.com/hobovsky/codot-client/blob/main/README.md#fixing-forks-beta), an AI-powered assistant, and its [fork refactoring](https://github.com/hobovsky/codot-client/blob/main/README.fixing.md#fixing-forks-with-codot-beta) function. From 2ed009d6871c9cdba78f6d29e24551f8199d8ee5 Mon Sep 17 00:00:00 2001 From: chabros Date: Sun, 2 Mar 2025 16:29:26 +0100 Subject: [PATCH 3/6] Adds link to HOWTO fix to the sidebar --- content/curation/howtos/fixing.md | 2 +- sidebars.js | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/content/curation/howtos/fixing.md b/content/curation/howtos/fixing.md index 02c89f1e..4f3289c7 100644 --- a/content/curation/howtos/fixing.md +++ b/content/curation/howtos/fixing.md @@ -16,7 +16,7 @@ The first step to fixing a Codewars kata is determining which kata need fixing i ## Creating a fork -A new fork can be initiated by opening the kata details page, selecting one of the available languages, and clicking the `Fork` button at the top right corner. This opens the fork editor, where all editors are populated with the current state of the corresponding code snippets in the selected language and description. This code can be edited and used as a starting point for a fix. +A new fork can be initiated by opening the kata details page, selecting one of the available languages, and clicking the `Fork` button in the top right corner. This opens the fork editor, where all editors are populated with the current state of the corresponding code snippets in the selected language and description. This code can be edited and used as a starting point for a fix. :::warning Do not fork outdated forks Fixes should not be applied by starting with a fork of an already approved fork. For example, when an issue is reported with a JavaScript version of a kata, it should be fixed by forking the current state of the kata, not by forking the original, approved JavaScript translation or the most recent JavaScript translation. The kata may have been modified after the translation was published and approved, and forking an old fork can revert changes applied afterward. diff --git a/sidebars.js b/sidebars.js index 6d6e4528..70e27558 100644 --- a/sidebars.js +++ b/sidebars.js @@ -96,6 +96,7 @@ module.exports = { items: [ "curation/kata", "curation/translation", + "curation/howtos/fixing", { type: "category", label: "Guidelines", From 0bfc87c2ca038ba9d690e5b68ebaca60aaeb9a46 Mon Sep 17 00:00:00 2001 From: chabros Date: Sun, 2 Mar 2025 18:48:06 +0100 Subject: [PATCH 4/6] Remove outdated information about translations --- content/curation/translation.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/content/curation/translation.md b/content/curation/translation.md index abe64c3f..6c938a50 100644 --- a/content/curation/translation.md +++ b/content/curation/translation.md @@ -48,8 +48,6 @@ When the translation is approved, a new language is immediately available for so The user who approved the translation should also go through the kata discourse and mark suggestions posted by the translator as resolved. -**NOTE:** at the time of writing, a user who _approves_ a translation is marked as a **kata contributor**. Users with the "contributor" flag seem to be affected by a bug preventing them from earning any future points they would be rewarded for authoring activities on kata they contributed to. Be aware that as a result, approving a translation will render you ineligible for honor points you would otherwise earn by translating, editing or fixing the kata in the future until the bug is fixed. - ### Merge Issues Oftentimes if two translations are created around the same time, they may both update the description. When approving the 2nd translation, the 1st approved translation will already have updated the description. This will cause a merge conflict which has to be resolved. @@ -70,20 +68,6 @@ Some possible reasons could be: It's worth noting that rejected translations are not wasted work. They are still available in the system, can be forked and used as a base for new translations, or its code can be simply copied and reused. -## Fixing existing translations - -Sometimes a kata needs to be fixed due to an issue, be it a bug in the reference solution, typos in the description or the lack of test coverage. Fixes and improvements to approved translations can be done in one of two ways: - -- If a translation was created with the translations panel, the most recent fork can be forked again, modified, and published. Afterwards it has to go through the usual translation review process and wait until another user approves it. However, translations created directly within the kata editor cannot be forked. -- A translation may be modified directly with the kata editor. This method allows for immediate changes without waiting for approval, but it also has some drawbacks: - - it requires privileges which are available only to experienced users, - - it invalidates existing forks, what may cause merge conflicts for modified snippets if someone publishes a fork of this translation sometime in the future, - - direct edits are not subject to the review process and other users cannot verify the introduced changes. - -:::warning -The way how kata edits are currently handled, existing pending forks can be very easily outdated by direct edits of the kata. When creating a fork based on some other, existing fork, you have to make sure that it contains the most current state of its language and does not overwrite or revert changes introduced with the kata editor. -::: - [translation-curating-guidelines]: /curation/guidelines/translation/ [translation-authoring-guidelines]: /authoring/guidelines/translation/ [privileges-reference]: /gamification/privileges/ From 346593545bfc49124ed78bbb7b37701750e2f475 Mon Sep 17 00:00:00 2001 From: chabros Date: Sun, 2 Mar 2025 18:48:56 +0100 Subject: [PATCH 5/6] Apply remarks from review --- content/curation/howtos/fixing.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/content/curation/howtos/fixing.md b/content/curation/howtos/fixing.md index 4f3289c7..e532efcd 100644 --- a/content/curation/howtos/fixing.md +++ b/content/curation/howtos/fixing.md @@ -10,7 +10,7 @@ The first step to fixing a Codewars kata is determining which kata need fixing i - On the [kata search page](https://www.codewars.com/kata/my-languages), every entry shows the number of pending issues (if any). - Posts on the home page [dashboard](https://www.codewars.com/dashboard/discourse/issues) can be filtered to display the most recently reported issues. -- The discourse page of every kata can be filtered for posts labeled as `ISSUE`. +- The discourse page of every kata can be filtered for posts labeled as `ISSUE` or `SUGGESTION`. - The [kata search page](https://www.codewars.com/kata/) can be used to find challenges that have not been updated to the latest version of their available languages. For example, to find kata with tests that need to be updated to the latest available version of JavaScript, filter for language: JavaScript, and manually add the parameter `&outdated=1` to the URL (example link to find all [outdated JavaScript kata](https://www.codewars.com/kata/search/javascript?q=&order_by=sort_date%20desc&outdated=1)). - The [`codewars/content-issues`](https://github.com/codewars/content-issues) GitHub repository hosts [wiki pages](https://github.com/codewars/content-issues/wiki) with lists of kata that need an update and an [issue board](https://github.com/codewars/content-issues/issues) with tickets related to kata maintenance. @@ -23,7 +23,7 @@ Fixes should not be applied by starting with a fork of an already approved fork. ::: :::warning Prefer forks to direct edits -Applying fixes via forks is preferred over updates done with the kata editor. Forks can be reviewed, and reviewers can share their remarks before approving the fix. +Applying fixes via forks is preferred over updates done using the kata editor. Forks can be reviewed, and reviewers can share their remarks before approving the fix. ::: ### Scope of a fix @@ -32,13 +32,13 @@ A single Codewars challenge can be affected by multiple problems. It may be temp A user must find a balance between making large-scale fixes that attempt to address many issues at once and smaller, incremental changes that are easier to review and approve. Sometimes, applying a series of small fixes is more effective than attempting to fix multiple issues in a single fork. -It is recommended to write a short post on a published fork explaining what problems it addresses. +It is recommended to write a short comment in the discourse of a published fork explaining what problems it addresses. ### Announcing the fork When a fork with a fix is ready, it needs to be published for review and potential merging. To notify reviewers about a fork ready for review, it can be helpful to announce the fix with a message posted in the discourse section of the kata (labeled as `SUGGESTION`) and in the `#fixing` channel of the Codewars Discord. -### Review of a fork +## Review of a fork After a fork with a fix is published and announced, it should attract the attention of reviewers who will evaluate it and either approve it or request further improvements. @@ -46,7 +46,11 @@ Users with sufficient privileges can approve their own forks without waiting for When a reviewer requests further improvements, they can be added to the same fork. It is not necessary to fork a fork if it hasn't been approved or rejected. However, if the fork has already been merged and further improvements are required, it must be re-forked. Editing an approved fork is possible, but there is no way to merge the new changes into the kata. -### Resources on fixing +## Pitfall: editing descriptions + +Updading a kata description, with a fork or in any other way, renders all pending translations and update forks of this kata impossible to approve due to description merge conflicts. While unfortunate, it is not a serious impediment for fixing activities, because merge conflicts are relatively [easy to fix](/curation/translation/#merge-issues). + +## Resources on fixing Users interested in fixing Codewars challenges have several resources at their disposal: From 8da567b37492fe1111164ce1aadfaddffa04105f Mon Sep 17 00:00:00 2001 From: chabros Date: Sun, 2 Mar 2025 18:54:24 +0100 Subject: [PATCH 6/6] Add missing info on editing a pending fork --- content/curation/howtos/fixing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/curation/howtos/fixing.md b/content/curation/howtos/fixing.md index e532efcd..44eb4696 100644 --- a/content/curation/howtos/fixing.md +++ b/content/curation/howtos/fixing.md @@ -44,7 +44,7 @@ After a fork with a fix is published and announced, it should attract the attent Users with sufficient privileges can approve their own forks without waiting for a review. -When a reviewer requests further improvements, they can be added to the same fork. It is not necessary to fork a fork if it hasn't been approved or rejected. However, if the fork has already been merged and further improvements are required, it must be re-forked. Editing an approved fork is possible, but there is no way to merge the new changes into the kata. +When a reviewer requests further improvements, they can be added to the same fork by its author. It is not necessary to fork a fork if it hasn't been approved or rejected. However, if the fork has already been merged and further improvements are required, it must be re-forked. Editing an approved fork is possible, but there is no way to merge the new changes into the kata. ## Pitfall: editing descriptions