Adding a comment feature for Achievement Editor

[NightlightBlackbird]

This is a feature mainly dealing with RALibretro, but I was suggested to put it in this repository due to it also affecting other features of RA.

Though we do already have Code Notes, it would be really great if there was a comment line feature in the Achievement Editor. I think it would be useful especially when it comes to noting the logic of achievements, labeling a group of conditions, explaining alt groups, etc. I sort of picture it being inserted between conditions and being able to be reordered like other conditions, so that you can see it on the editor at-a-glance rather than having to hover your cursor over a condition to get the information. ...But any sort of comment feature would be nice.

[suspect15]

I was going to suggest this very thing. I think it would be immensely helpful for resolving inactive dev tickets (that have the notes) as well as our own achievements, especially if it has been a while since we created them.

Using myself as an example, if this achievement got a ticket and I was no longer active, I think this would be extremely difficult to dissect without understanding why I created 4 alt groups: https://retroachievements.org/achievement/264382

If I were to explain that in a short note, in the game, the most efficient way to measure yardage gained on a play requires different techniques for non-touchdown gains and plays that score a touch downs and that each alt group represents a different potential satisfactory condition in the different cases needing to be measured:
alt 1: neither rush nor pass scores a touchdown
alt 2: rush is not a touchdown, pass is a touchdown
alt 3: rush is a touchdown, pass is not a touchdown
alt 4: both are touchdowns

Hopefully, being able to read the above paragraph, you could pretty easily understand why the achievement is structured the way it is and it would make trouble shooting much easier. That would not only help future people needing to resolve inactive dev tickets, but I think would also be helpful for solving your own tickets that you may not have thought about in a long time.

[redwizard42]

Been thinking about this. Wondering what would be best.

1. One comment per achievement (achievement-level comments) as additional meta data.
2. One comment per group (not exactly sure how this would serialize sanely)
3. Comments-as-conditions. Would be flexible in placement, but probably doesn't play nicely with the existing grid-based presentation in the achievement editor.
4. Each condition has an optional comment field. -- This seems the most doable to me, but does run the risk of developers going nuts commenting every condition and filling up their character limit. Could also lead to higher memory usage unless we do something like strip out comments when sending achievement logic to non-development tools (i.e. anything not using ra_integration/have the consumer specifically request "include comments").

[wescopeland]

Depending on how comments are stored, we could ensure the Connect API doesn't send them to consumers unless it's explicitly requested.

[redwizard42]

Quick hit ideas of varying reasonableness and frailty:

• Being now mindful of the regex for splitting the serialized string for display, rather than in-line text, perhaps a simpler idea would be some delimiter (like .###. for hits) around a comment ID (local for local achievements, otherwise stored on server in a comments table) that is a lookup into a comments table. Problem here is that it still counts towards the character limit, and there are concerns about keeping it in sync and also orphaning comments.
• Some way to link a comment to an achievement or leaderboard, and then point to a specific condition [within a specific section]. Feels fragile and prone to becoming unsynched.
• Comment condition that has an index to a comment (presentation may be problematic
• One [big] achievement comment as part of the achievement data.

Presentation thoughts

• If comments "attached" to conditions, could add another column to the editor with optional popup/visualizer to more extensive text editing. Pros: Right there next to relevant logic
• If comments are a condition (index to a comment in database/local), is it possible to have the text span across cells in the grid?

[redwizard42]

Opened a poll on discord for developers to weigh in with what they might prefer (including "nothing") just to inform design.

[redwizard42]

Polling results were as follows:
Question
Developers, if there were an ability to have comments in achievement logic, what would be your preference?

Choices
🇦 One per achievement in order to give a general explanation of logic
🇧 Comments as conditions that I can move up and down like other conditions.
🇨 Optional comment fields on each condition.
🇩 A & B
🇪 A & C
🇫 I wouldn't want comments

Final Result
🇦 ▓▓░░░░░░░░ [6 • 21%]
🇧 ▓▓░░░░░░░░ [5 • 17%]
🇨 ▓▓▓░░░░░░░ [8 • 28%]
🇩 ░░░░░░░░░░ [1 • 3%]
🇪 ▓▓▓░░░░░░░ [9 • 31%]
🇫 ░░░░░░░░░░ [0 • 0%]
29 users voted

[redwizard42]

Combining choices,
15/29 Are accepting of A (A comment field on the achievement for additional information)
17/29 Are accepting of C (Optional comment fields on each condition)
5/29 Are accepting of B (comments as conditions that can be positioned in the conditions list.

My thoughts based on this is that it may be good in the short term to add A to the achievement metadata, with an eye on designing something that would allow C.

[suspect15]

Option A would allow for the most flexibility - it'd be a great initial capability. I definitely also see a lot of value in Option C, assuming the note would remain attached to the condition logic instead of the condition number. I could see it getting messing if updating an achievement with Option C comments and the comments didn't follow their associated logic when shuffling things around.