Title change system notes should be moved to resource_*_events

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

I'm opening this issue to discuss a potential implementation of a feature request surfaced in #536827 (closed).

Currently, "title change" events are tracked as general system notes, increasing the difficulty of tracking these events independently: any consumer who wishes to track title changes for an issue must get all of the issue notes, and parse the body field for a .* changed title .* message. This leads to fragility: any changes to the format of this field may cause downstream breakage (as seen in #536827 (closed)).

Having a dedicated API for these events would improve the consumer experience. This is applicable to all system notes, however, this issue is being filed specifically for title change events.

---

I should note that a comment by @engwan indicates that while this approach would align with label and state changes that were implemented previously, it does come at the expense of adding another endpoint (or two) to the requests that the frontend needs to make before it can render the system notes.

This is not ideal, in my opinion, and as such, I'd like to present the idea that issue notes, in general, retain the same "single endpoint" approach, however, to achieve the same goal as this issue hopes to, the response object could be refactored to more strictly match issue notes as a first class citizen. That might look something like:

[
  {
    "kind": "TITLE_CHANGE",
    "value": "some new title with <code>some formatted text</code>",
    "previous_value": "some old <code>title</code>",
    "markdown": "<p>changed title from <code class=\"idiff\">...</code> to <code class=\"idiff\">...</code></p>",
    ...
  },
  {
    "kind": "COMMENT_ADD",
    "value": "...", # not sure if there's a purpose for this...
    "markdown": "This is a comment\n\nfoo\nbar\nbaz",
    ...
  },
]

For the use case described in this issue and in #536827 (closed), this would suffice, but the different types of notes may lead to difference in field presence for different objects (as visible from the above example: there's not necessarily a need for COMMENT_ADD events to have both a value and markdown field, and it definitely doesn't need a previous_value field. This discrepancy is not ideal and indicative of this being a suboptimal solution.

Perhaps what fits both needs and is more appropriate for a multi-entity endpoint like the existing issue notes API is the addition of another field or two, like event_object and kind, where event_object contains the custom-field-per-event object that makes parsing these events easier.

I dunno, it's things like this that make graphql an attractive solution for frontends: clear entity separation and a single call.