Epic: "Meta Data Table" in Issue Description

[nelsonic]

As a user of the GitHub Backup App,
I want to see at a glance if an issue has "version history"
so that I know there is "history" and I can click to see it!

Acceptance Criteria

• Meta Table should be inserted into the issue description when the issue is Created.

  • a comment advising people not to delete/change it.
    e.g: <!-- avoid editing below this line to preserve issue history --> (see below)

• Minimise space occupied by the table to Two Rows to avoid clutter:
  Heading (Key) & Row-Cell (Value) >> see below for example.

• Display the revision count for the issue.
  We already have a "Proof of Concept" for using SVG as a Counter: http://hits.dwyl.io
  e.g:

• Display a "short link" (dependent on the App / Domain Name chosen. see: Project / App Name ? #13)

Optional (Nice-to-Have)

• Subtle Color/Branding in the table.

Question / Discussion:

What other info would it be useful to display in the "Meta Table"?
(or should we "keep it simple for MVP and ask users once deployed...?)

Example:

Issue Edit Count	View History
9	gibu.io/dwhq321

Note: I would prefer to have a single-line table (for even less "clutter") e.g:

+---------------------+-------------------------------+
| Issue Edit Count: 9 | View History: gibu.io/dwhq321 |
+---------------------+-------------------------------+

But sadly markdown does not support it:
https://stackoverflow.com/questions/17536216/create-table-without-header-in-markdown

[SimonLab]

What other info would it be useful to display in the "Meta Table"?

I think the example (number of time the issue has been edited and link to the history view) is a good start for an MVP! If this table works it will be easy to add more info but more complicated to remove existing data (maybe not too much technically but from the user experience it might feels strange)

Is the meta table represents any edits (on the issue description and on the comments of the issue)? If yes I think it makes sense to only display the meta table on the description issue. We might need to find a way to explain this on the meta table (ie. "Issue/Comments Edit Cout" 🤔 ) as it might not be obvious at a first sight.

[nelsonic]

@SimonLab good question. I feel that we should test this.
(i.e. Meta Table in first comment vs. any comment with edits ...)

Most comments don't have edits so it won't be too bad if we have the Meta Table in any comment that has an edit.
My "fear" is that we add a table to a one-line comment where someone fixed a typo.
It would "clutter" the comment ... 🤔

For now (MVP) let's only insert the Meta Table in the first comment and then get User-Feedback on the Feature ...

[SimonLab]

Thanks for the clarification @nelsonic and agree let's focus on the edit history of the issue description instead of the comments at least for the MVP.

The only other information I would add on the meta table is a link/logo to the github app on the marketplace so that users can install the app easily via the meta table

[nelsonic]

@SimonLab on the subject of having a link/logo in the Meta Table,
initially I would prefer to "limit self promotion" in the Issue description/comment(s)
as it does not add any value to the UX ... 🤔
Can we open an issue to discuss this separately?
(we might need this promo in order to reach the 250 downloads #17 ...)
The fact that the "short link" will have our "brand" in it should be good "promo" for now ...

[Cleop]

@nelsonic - what priority do you think this should be? Perhaps 2 or 3?

[nelsonic]

As soon as we are tracking the history of an repo's issues we want to make that clear.
(hence priority-2...) 👍

[Cleop]

@nelsonic @SimonLab - if we only display the table in top comment then where would clicking on the link take you? At the moment we're organising history pages by each comment not by issue. So on that basis I would start with having one per comment (where edits exist).

@nelsonic - so for the MVP are you suggesting we do the first comment (with the number of edits of all comments on the issue) or the first comment with just # edits listed for that one comment?

First step:

• add text to the issue description on 'issue_edited' event - thoughts: if we're going to edit the comment each time by adding/updating the table in the comment, surely those will change the number of edits and we'd get stuck in an infinite loop? We'll have to filter out events by our app as the author to make sure this doesn't happen and they're not counted.

Notes on API Patch Method
The HTTP methods PATCH can be used to update partial resources. For instance, when you only need to update one field of the resource, PUTting a complete resource representation might be cumbersome and utilizes more bandwidth

Also, the PUT method is idempotent. PUTting the same data multiple times to the same resource, should not result in different resources, while POSTing to the same resource can result in the creation of multiple resources.

I also agree, the smaller the table, the better.

This is what the table looks like with a blank header which is one option:

Issue Edit Count: 9	View History: gibu.io/dwhq321

[nelsonic]

@Cleop, Yeah, I'm suggesting that we User Test this by including the table in the first comment (AKA "Issue Description") to avoid clutter. and then to make it configurable later.

The history page should be for the whole issue.
and inside that page should have "anchor" links to the comments
and their respective version history.
it should be one page regardless of how many comments and versions.
unless it takes "ages" to load (which we can "optimise later").

Also, yes, the table will only be inserted into the First Comment exactly Once.
And then the Number of Edits will be a dynamic SVG (i.e "Badge")
as per: https://github.com/dwyl/hits-elixir though we will only use a number without any color or style.
(hence me getting you to "Grock" that codebase before we started work on this project...)

Our app will know to ignore edits/updates made by the app. so there will be no "infinite loop" 🔁