Add: Refactoring Requirements doc

docs/.vitepress/config/en.ts

@@ -278,6 +278,10 @@ function sidebarGuidelines(): DefaultTheme.SidebarItem[] {
           text: "Hash Labels",
           link: "/guidelines/content/hash-labels",
         },
+        {
+          text: "Refactoring Requirements",
+          link: "/guidelines/content/refactoring-requirements",
+        },
       ],
     },
   ];

docs/.vitepress/config/es.ts

@@ -274,6 +274,10 @@ function sidebarGuidelines(): DefaultTheme.SidebarItem[] {
         //   text: "Etiquetado de hashes",
         //   link: "/es/guidelines/content/hash-labels",
         // },
+        // {
+        //   text: "Requisitos de Refactoring",
+        //   link: "/es/guidelines/content/refactoring-requirements",
+        // },
       ],
     },
   ];

docs/.vitepress/config/pt.ts

@@ -274,6 +274,10 @@ function sidebarGuidelines(): DefaultTheme.SidebarItem[] {
     //       text: "Etiquetas de Hash",
     //       link: "/pt/guidelines/content/hash-labels",
     //     },
+    //     {
+    //       text: "Requisitos de Refactoring",
+    //       link: "/pt/guidelines/content/refactoring-requirements",
+    //     },
     //   ],
     // },
   ];

docs/guidelines/content/refactor-requirements.md

@@ -0,0 +1,64 @@
+---
+title: Refactoring Requirements
+description: This guide covers the requirements for refactoring a substandard, inactive developer's set.
+---
+
+# Refactoring Substandard Sets
+
+[[toc]]
+
+# Refactoring Overview
+
+Refactoring a set on RetroAchievements is the act of bringing a substandard, inactive developer set up to modern standards. Ridding the library of poorly noted, coded, and implemented sets is the only way RetroAchievements can attain longterm stability. This doc provides guidance on what is required to bring a set up to modern standards and consider it no longer an instability risk to the project. Once a refactor is completed in accordance with these guidelines, the set can be marked by QA as "refactored" and should be considered stable in perpetuity.
+
+**A refactored set should be able to pass a code review without needing corrections.**
+
+# Finding a Set to Refactor
+
+Only sets that are in the [Needs Refactoring hub](https://retroachievements.org/hub/3389) are eligible to be refactored.
+
+# The Refactoring Process
+
+The following aspects of a set must all be up to modern standards in order to be considered refactored and no longer in need of additional improvement:
+- Code Notes
+- Achievement Logic
+- Leaderboard Function and Logic
+- Title and Description Writing
+- Rich Presence
+
+## Code Notes
+
+Code notes must, at a minimum, contain the address's size, a description of what the address does or why it is used in the achievement code, and enumerated values and their associated.
+- Values must be in hexidecimal or float format, listed in increasing value by default
+
+## Achievement Logic
+
+Achievement logic must be free of bad practices such as lack of Mem/Delta checks, unnecessary use of hits, resets, and pauses, and unnecessarily complex or extraneous logic.
+- Many older sets were inadequately RAM dug and will likely benefit from or require additional RAM digging in order to ensure proper addresses are used
+
+## Leaderboard Function and Logic
+
+Any leaderboard that submits a value tracked in-game should be instantaneous, not primed, unless there is an exceptionally compelling reason. Instantaneous leaderboards reduce screen clutter and are much more simple to code and maintain. Leaderboard logic is held to the same expectations as achievement logic.
+
+## Title and Description Writing
+
+At a minimum, gross errors such as miscapitalization, unnecessary parentheticals, and grammar mistakes should be corrected. If writing is generally poor, the set should be referred to the [WritingTeam](https://retroachievements.org/user/WritingTeam) so they can put it into the [Noncompliant Writing hub](https://retroachievements.org/hub/24397).
+
+## Rich Presence
+
+Rich Presence must be dynamic and free of useless information. Unclear emojis and superfluous language should be removed to ensure RP is clear, concise, and understandable by site viewers who may not be particularly familiar with the game.
+
+# Save States
+
+Collecting save states during the refactoring process will make future maintenance significantly easier. Eventually on site storage may be available, so collecting complete sets of save states is highly desired during the refactoring process. Save states should use the most [recommended core](https://docs.retroachievements.org/general/emulator-support-and-issues.html) and its most current version.
+
+States should be collected so all achievements are easy to access and reported issues should be easily repeatable. In general, the following are the states that should be collected:
+
+- Prior to any boss fights that have associated achievements for progression, collection, or challenge
+- Prior to obtaining the last item, skill, or level for collection/power-up achievements
+- Prior to the beginning of a challenge's initial checkpoint hit
+- Periodically at sensible points throughout standard gameplay to give general access to all parts of the game
+
+# Refactor Notification
+
+Upon fully completing a refactoring, developers should notify [QATeam](https://retroachievements.org/user/QATeam) via site message. QA will confirm the set meets full refactor criteria and remove it from the Needs Refactoring hub.