#82 Assigning a short ID number/code to issues

Open
opened 2 months ago by fr33domlover · 4 comments

The Create flow for reporting an issue introduces the possibility to have ticket URLs that are on different servers. When a ticket is created, it's no longer possible to immediately attach a short numeric ID number like #123. Tickets would have just a title and a description.

Do we want/need to support those numeric codes, or some other short way to refer to tickets?

IDEA: When a repo Accepts a ticket, it attaches a new numeric ID to it! Even if none of the tickets have a numeric ID in their URL, tickets can still have those numbers assigned by the repo server and displayed in UI and used in commit messages to automatically close tickets, and be used in pieces of text (ticket descriptions, MRs, patches, etc.) to refer to tickets.

If we do that, which property do we use for that? I think it would have to be a custom one, because the standard reasonable ones are all taken. name is already used for the ticket title. We could however use Dublin Core title for the title, and let name be used for the numeric ID.

The `Create` flow for reporting an issue introduces the possibility to have ticket URLs that are on different servers. When a ticket is created, it's no longer possible to immediately attach a short numeric ID number like `#123`. Tickets would have just a title and a description. Do we want/need to support those numeric codes, or some other short way to refer to tickets? IDEA: When a repo `Accept`s a ticket, it attaches a new numeric ID to it! Even if none of the tickets have a numeric ID in their URL, tickets can still have those numbers assigned by the repo server and displayed in UI and used in commit messages to automatically close tickets, and be used in pieces of text (ticket descriptions, MRs, patches, etc.) to refer to tickets. If we do that, which property do we use for that? I think it would have to be a custom one, because the standard reasonable ones are all taken. `name` is already used for the ticket title. We could however use Dublin Core `title` for the title, and let `name` be used for the numeric ID.
fr33domlover commented 2 months ago
Collaborator

(See related issue #20)

(See related issue #20)

Numeric ID's don't really work in a federated environment. This would be a non-standard way of mentioning in ActivityPub and requires additional implementation for platforms. Also, consider;

  • Server A sends Create { Ticket } to Server B
  • Server B sends Accept back to Server A, generating a numerical ID.

How does Server C get the numerical ID? Server A probably doesn't even know about it. Server B would not only have to send an inbox forwarding Create to Server B, but also an Update to push the numerical ID through.

This creates complexity and degrades the idea that the object is generated fully by one author + makes Accept something that updates remote objects, which feels wrong by itself.

SUGGESTION: keep to the standard ways of mentioning on the fediverse ie using a Mention tag as shown here: https://www.w3.org/TR/activitystreams-vocabulary/#microsyntaxes

Basically a mention to an issue, PR, etc, would contain something like:

"tag": [
    {
      "type": "Mention",
      "href": "http://example.org/issues/1",
      "name": "<display name>"
    }
]

The name can be anything really, it's not specified by spec. Normally one would expect it to be the "display name of the rendered link to the mentioned object" but in practice in the real world I haven't seen it used - possibly somewhere? It would make sense to document an example in Forgefed at SHOULD level maybe to highlight how mentions would be rendered? Maybe suggesting the title of the issue / pr or display name/username of user for example, depending on the object?

Numeric ID's don't really work in a federated environment. This would be a non-standard way of mentioning in ActivityPub and requires additional implementation for platforms. Also, consider; * Server A sends `Create { Ticket }` to Server B * Server B sends `Accept` back to Server A, generating a numerical ID. How does Server C get the numerical ID? Server A probably doesn't even know about it. Server B would not only have to send an inbox forwarding `Create` to Server B, but also an `Update` to push the numerical ID through. This creates complexity and degrades the idea that the object is generated fully by one author + makes Accept something that updates remote objects, which feels wrong by itself. SUGGESTION: keep to the standard ways of mentioning on the fediverse ie using a `Mention` tag as shown here: https://www.w3.org/TR/activitystreams-vocabulary/#microsyntaxes Basically a mention to an issue, PR, etc, would contain something like: ``` "tag": [ { "type": "Mention", "href": "http://example.org/issues/1", "name": "<display name>" } ] ``` The `name` can be anything really, it's not specified by spec. Normally one would expect it to be the "display name of the rendered link to the mentioned object" but in practice in the real world I haven't seen it used - possibly somewhere? It would make sense to document an example in Forgefed at SHOULD level maybe to highlight how mentions would be rendered? Maybe suggesting the title of the issue / pr or display name/username of user for example, depending on the object?
fr33domlover commented 2 months ago
Collaborator

@jaywink, thanks for feedback. I'm okay with doing mentions like that. Actually I think we should do them like that regardless of whether we have numeric IDs or not. Those numeric IDs are just a UI/human thing; the mention would be represented the same way in AP anyway.

In ikiwiki, page URLs are simply based on the user entered title text. No numeric IDs. But everywhere else, those IDs exist.

Mitigation of problem with storing numeric ID

One idea: Store the ID on the repo side, without sending it to the author. But then, if people HTTP GET the ticket, they don't see the ID there.

Another idea, put it in the Accept. Then, like you said, Accept modifies a remote resource. Hmmm.

Another option, send an Update. But that increases complexity a bit.

Hmmm how about the following: What if those numeric IDs are set by the entity that hosts the ticket? For example all the tickets you create, you give them a short code. Say, a number. "1", "2" and so on. The numbers are assigned on your server.

Now suppose someone wants to mention a ticket you opened. Normally on forges, they'd type something like #123, right? Instead, imagine they type something like @jaywink#123. The client UI lets them complete the @jaywink reference into your full ID, and the #123 part is completed into the full ticket ID URI. For compatibility, when someone types just #123, UI can assume they mean a ticket hosted by the repo itself.

So when you Create Ticket, you assign a short ID to it. Repos would no longer have IDs like "#1, "#2", "#3" and so on; they'd look more like this:

  • @jaywink#99
  • @zPlus@notabug.org#TICKET-82734
  • @fr33@host.tld#113

This looks kinda weird though, doesn't it? Does this have any benefits at all? Which leads us to:

Why have those short ticket IDs at all

Where are they used?

  • People could mention them in other tickets and in MRs
  • People could mention them in ticket comments
  • People could mention them in commit messages to auto-close tickets

But do we need those IDs? It's totally possible that when you want to mention a ticket, you type in a reference/mention of the repo itself, and then UI shows you a list of ticket titles and auto-completes as you start to type the one you want. Then, tickets are referred by the title text and there's no need for the number. But then, I wonder about the actual microsyntax we'd use for mentioning tickets.

Is it enough to use have an HTTP link to the the mentioned ticket?

When I mention a ticket that you're hosting, it's important that you're added to the recipients of the activity I'm posting, so that your ticket knows it has been mentioned and UI can display that info. How do I write the ticket mention, in such a way that software knows the ticket author should be addressed in the "to" field? In Mastodon we don't have that thing, because:

  1. You can't edit toots, so there's no source form to keep, simply generate the final HTML
  2. The only thing you can mention is actors, and then the actor gets addressed

We may need some new behavior here, where you can write a simple Markdown/HTML link to some object, and then the software needs to HTTP GET this object and check its attributedTo or something like that, and address that actor. Or we invent some new micro syntax. (Hmm also, for tickets opened using the Offer flow, checking attributedTo may not be enough if that property indicates the author and not the repo actor, need to look at context or something like that)

Existing forges often use those numeric codes, but we don't have to pick a standard way to represent them in ForgeFed until there's real world need for that.

Do we need a micro syntax

Q: Is it important to pick a standard micro syntax?

A: Let's see. Suppose I open a ticket, and I use some custom thing in the Markdown source, to mention some other tickets. My client / my server understands this syntax and detects the mentions and makes sure the authors of the tickets I mentioned receive my Create Ticket activity. Now suppose you, from another server, want to edit the ticket. Your software however uses a different micro syntax. When you publish your Update Ticket, your client / your server detects any new mentions you added, and the authors of the mentioned tickets receive the activity.

In other words, as long as we let the author report mentions, a single standard micro syntax isn't critical.

And what if some servers want to be in charge of this and be sure authors were notified? I guess that would complicate things a bit, but, why would servers need to be in charge of that in the first place? Maybe that's not an important use case :)

Conclusion

Shall we try not having short ticket IDs or a standard micro syntax for mentioning tickets, and see how it goes?

@jaywink, thanks for feedback. I'm okay with doing mentions like that. Actually I think we should do them like that regardless of whether we have numeric IDs or not. Those numeric IDs are just a UI/human thing; the mention would be represented the same way in AP anyway. In ikiwiki, page URLs are simply based on the user entered title text. No numeric IDs. But everywhere else, those IDs exist. # Mitigation of problem with storing numeric ID One idea: Store the ID on the repo side, without sending it to the author. But then, if people HTTP GET the ticket, they don't see the ID there. Another idea, put it in the `Accept`. Then, like you said, `Accept` modifies a remote resource. Hmmm. Another option, send an `Update`. But that increases complexity a bit. Hmmm how about the following: What if those numeric IDs are set by the entity that hosts the ticket? For example all the tickets you create, you give them a short code. Say, a number. "1", "2" and so on. The numbers are assigned on *your* server. Now suppose someone wants to mention a ticket you opened. Normally on forges, they'd type something like `#123`, right? Instead, imagine they type something like `@jaywink#123`. The client UI lets them complete the `@jaywink` reference into your full ID, and the `#123` part is completed into the full ticket ID URI. For compatibility, when someone types just `#123`, UI can assume they mean a ticket hosted by the repo itself. So when you `Create Ticket`, *you* assign a short ID to it. Repos would no longer have IDs like "#1, "#2", "#3" and so on; they'd look more like this: - `@jaywink#99` - `@zPlus@notabug.org#TICKET-82734` - `@fr33@host.tld#113` This looks kinda weird though, doesn't it? Does this have any benefits at all? Which leads us to: # Why have those short ticket IDs at all Where are they used? - People could mention them in other tickets and in MRs - People could mention them in ticket comments - People could mention them in commit messages to auto-close tickets But do we need those IDs? It's totally possible that when you want to mention a ticket, you type in a reference/mention of the repo itself, and then UI shows you a list of ticket titles and auto-completes as you start to type the one you want. Then, tickets are referred by the title text and there's no need for the number. But then, I wonder about the **actual microsyntax** we'd use for mentioning tickets. Is it enough to use have an HTTP link to the the mentioned ticket? When I mention a ticket that you're hosting, it's important that you're added to the recipients of the activity I'm posting, so that your ticket knows it has been mentioned and UI can display that info. How do I write the ticket mention, in such a way that software knows the ticket author should be addressed in the "to" field? In Mastodon we don't have that thing, because: 1. You can't edit toots, so there's no source form to keep, simply generate the final HTML 2. The only thing you can mention is actors, and then the actor gets addressed We may need some new behavior here, where you can write a simple Markdown/HTML link to some object, and then the software needs to HTTP GET this object and check its `attributedTo` or something like that, and address that actor. Or we invent some new micro syntax. (Hmm also, for tickets opened using the Offer flow, checking `attributedTo` may not be enough if that property indicates the author and not the repo actor, need to look at `context` or something like that) Existing forges often use those numeric codes, but we don't have to pick a standard way to represent them in ForgeFed until there's real world need for that. # Do we need a micro syntax Q: Is it important to pick a standard micro syntax? A: Let's see. Suppose I open a ticket, and I use some custom thing in the Markdown source, to mention some other tickets. My client / my server understands this syntax and detects the mentions and makes sure the authors of the tickets I mentioned receive my `Create Ticket` activity. Now suppose you, from another server, want to edit the ticket. Your software however uses a different micro syntax. When you publish your `Update Ticket`, your client / your server detects any new mentions you added, and the authors of the mentioned tickets receive the activity. In other words, as long as we let the author report mentions, a single standard micro syntax isn't critical. And what if some servers want to be in charge of this and be sure authors were notified? I guess that would complicate things a bit, but, why would servers need to be in charge of that in the first place? Maybe that's not an important use case :) # Conclusion Shall we try not having short ticket IDs or a standard micro syntax for mentioning tickets, and see how it goes?
sebhoss commented 4 weeks ago

How about a mixture of both? Using something like https://github.com/ai/nanoid we could have a URL-friendly IDs that are more or less guaranteed to be unique across multiple instances.

IMHO projects of a reasonable sice and life time do have a whole lot of tickets and it becomes harder and harder to remmeber that the right ticket is #123423429 or was it #123533429 or actually #123523429? I think it is impossible to type those IDs from memory and much easier to just copy the ID from another ticket. UI can help here, e.g. gitlab has this copy-reference feature in the lower right corner of a ticket or merge request.

On the other hand using something like #123@instance/repo (or any other of the proposed microsyntax) would feel more normal for people who are used to numerical ticket IDs.

Personally, I don't care whether a ticket Id is #123533429 or #Uakgb_J5m9g-0JDMbcJqLJ and thus would avoid short ticket IDs.

How about a mixture of both? Using something like https://github.com/ai/nanoid we could have a URL-friendly IDs that are more or less guaranteed to be unique across multiple instances. IMHO projects of a reasonable sice and life time do have a whole lot of tickets and it becomes harder and harder to remmeber that the right ticket is #123423429 or was it #123533429 or actually #123523429? I think it is impossible to type those IDs from memory and much easier to just copy the ID from another ticket. UI can help here, e.g. gitlab has this copy-reference feature in the lower right corner of a ticket or merge request. On the other hand using something like `#123@instance/repo` (or any other of the proposed microsyntax) would feel more normal for people who are used to numerical ticket IDs. Personally, I don't care whether a ticket Id is `#123533429` or `#Uakgb_J5m9g-0JDMbcJqLJ` and thus would avoid short ticket IDs.
Sign in to join this conversation.
Loading...
Cancel
Save
There is no content yet.