#48 Property for titles

Open
opened 1 month ago by fr33domlover · 4 comments

The use of AS2 for titles has been discussed a bit, and I'd like to reach some conclusion :)

For Commit, I've been using name for the title (and a custom description for the rest of the commit message; there's a separate thread discussing why they're in separate properties). But I just noticed that for Ticket, I'm using summary for the title and content for the description. So there are 2 differences:

  • The description/content difference is a bit weird, but not critical at this point: For a commit, the message is just a description because the commit itself is in the VCS, while for a ticket, the message is the ticket, it doesn't just describe some other object. Thoughts welcome, but also I don't mind leaving this as is, at least for now.
  • The name/summary distinction bothers me much more, I want to pick one of them.

So, name is plain text while summary is HTML, but HTML can contain plain text too, by having no tags and by being HTML-escaped and XSS-sanitized and so on. If there's a need for HTML, e.g. if ticket titles normally support Markdown or other forms of rich text, then summary is probably the better choice. Otherwise, we can usename` and then people don't need to sanitize etc. ticket titles, and their editing UI is simpler.

I've been using Ticket name for the ticket number, for display in UI, but it's possible to use the slug property for this instead.

Do some forges support rich text in ticket titles? It sounds like something that can make sense, idk, but curious if some ticket trackers or forges support that.

  • Gitea: Nope, just plain text (checked in try.gitea.io)
  • GitLab CE: Nope, plain text but URLs are detected and displayed as links
  • Trac: Nope, plain text (checked in Trac 1.2 demo and in ticket preview on Trac's own Trac)
  • Ikiwiki: Nope, plain text
  • OpenProject: Didn't check, but I looked at their own kanban and all titles there are plain text, including ones that could enjoy some formatting

Ah, summary also has the problem that there's no standard way to edit it! Because it's rendered HTML. So we'd need to define a way to provide the source of the summary. However name is plain text so it can be edited as is.

Thoughts? :)

Feneas forum thread

The use of AS2 for titles has been discussed a bit, and I'd like to reach some conclusion :) For `Commit`, I've been using `name` for the title (and a custom `description` for the rest of the commit message; there's a separate thread discussing why they're in separate properties). But I just noticed that for `Ticket`, I'm using `summary` for the title and `content` for the description. So there are 2 differences: - The description/content difference is a bit weird, but not critical at this point: For a commit, the message is just a description because the commit itself is in the VCS, while for a ticket, the message *is* the ticket, it doesn't just describe some other object. Thoughts welcome, but also I don't mind leaving this as is, at least for now. - The name/summary distinction bothers me much more, I want to pick one of them. So, `name` is plain text while `summary` is HTML, but HTML can contain plain text too, by having no tags and by being HTML-escaped and XSS-sanitized and so on. If there's a **need** for HTML, e.g. if ticket titles normally support Markdown or other forms of rich text, then `summary` is probably the better choice`. Otherwise, we can use `name` and then people don't need to sanitize etc. ticket titles, and their editing UI is simpler. I've been using `Ticket` `name` for the ticket number, for display in UI, but it's possible to use the [slug](https://talk.feneas.org/t/slug-namespace-and-managedby-properties/182) property for this instead. Do some forges support rich text in ticket titles? It sounds like something that can make sense, idk, but curious if some ticket trackers or forges support that. - Gitea: Nope, just plain text (checked in try.gitea.io) - GitLab CE: Nope, plain text but URLs are detected and displayed as links - Trac: Nope, plain text (checked in Trac 1.2 demo and in ticket preview on Trac's own Trac) - Ikiwiki: Nope, plain text - OpenProject: Didn't check, but I looked at their own kanban and all titles there are plain text, including ones that could enjoy some formatting Ah, `summary` also has the problem that there's no standard way to edit it! Because it's rendered HTML. So we'd need to define a way to provide the `source` of the `summary`. However `name` is plain text so it can be edited as is. Thoughts? :) [Feneas forum thread](https://talk.feneas.org/t/property-for-titles/183)
zPlus commented 1 month ago
Owner

In AP, summary is used to describe the activity for a human reader. I think we agreed it's better not to use that property. Commits per se do not have a "title" or a "name", only a description (the title is usually the first line of the description message). Tickets do have a title. We could use title for both, or only for tickets and let clients decide how to deal with commits messages.

In AP, `summary` is used to describe the activity for a human reader. I think we agreed it's better not to use that property. Commits per se do not have a "title" or a "name", only a description (the title is usually the first line of the description message). Tickets do have a title. We could use `title` for both, or only for tickets and let clients decide how to deal with commits messages.
fr33domlover commented 1 month ago
Collaborator

@zPlus,

  • We agreed not to use summary for activity display, but haven't talked about using it in general for summaries and titles of stuff. That's why I'm asking :)
  • Commits currently do have a title and a description, look at the forum thread linked in #24. If you have thoughts about representing commit titles / objection to the current way, please comment there on issue/thread.
  • Commit titles being plain text is established either way; I'm asking more for ticket titles and MR titles and CI recipe titles and so on.
  • Outside of AP, e.g. in Dublin Core, there's a title property. I haven't used it because I've been trying to reuse standard AP properties, and usually name can be used for the title. But it's a good point: Should we use title from DC for titles of stuff? What are the pros and cons?
@zPlus, - We agreed not to use `summary` for activity display, but haven't talked about using it in general for summaries and titles of stuff. That's why I'm asking :) - Commits currently do have a title and a description, look at the forum thread linked in #24. If you have thoughts about representing commit titles / objection to the current way, please comment there on issue/thread. - Commit titles being plain text is established either way; I'm asking more for ticket titles and MR titles and CI recipe titles and so on. - Outside of AP, e.g. in Dublin Core, there's a `title` property. I haven't used it because I've been trying to reuse standard AP properties, and usually `name` can be used for the title. But it's a good point: Should we use `title` from DC for titles of stuff? What are the pros and cons?
zPlus commented 1 month ago
Owner

We agreed not to use summary for activity display, but haven't talked about using it in general for summaries and titles of stuff.

at this point I think it's better to use something else with a different meaning than the existing summary, if we need users to provide a summary of something. But probably we don't even need it, "name" and "content" or "description" should cover any case

Commit titles being plain text is established either way; I'm asking more for ticket titles and MR titles and CI recipe titles and so on

I would simply define plain text everywhere, or maybe something standard like commonmark

> We agreed not to use summary for activity display, but haven't talked about using it in general for summaries and titles of stuff. at this point I think it's better to use something else with a different meaning than the existing `summary`, if we need users to provide a summary of something. But probably we don't even need it, "name" and "content" or "description" should cover any case > Commit titles being plain text is established either way; I'm asking more for ticket titles and MR titles and CI recipe titles and so on I would simply define plain text everywhere, or maybe something standard like commonmark
fr33domlover commented 1 month ago
Collaborator

"name" and "content" or "description" should cover any case

We need to be sure we want plain text. It seems to be what happens in reality, even web based and wiki based ticket trackers seem to use plain text there, but if there's any reason that someone would start supporting even little markup in titles, that's a point for summary or something else that is HTML. The examples in the AP spec use summary for object descriptions, so it's something that AP implementations may do.

I would simply define plain text everywhere, or maybe something standard like commonmark

Sure, me too, but remember we aren't just defining: We're modeling something to suit the real world situation, which includes both potential ForgeFed implementations, and everything else that uses ActivityPub:

  • If we go with plain text, we can just use name for the user entered title (or the Dublin Core title, but either way, no big dilemma here)
  • If we go with CommonMark, we need to deal with summary and source. In ActivityPub there's a single property for the source of the rendered HTML, and that's source. And it's only for content. So I find myself asking, do we follow the AP convention where rich content is federated in rendered form (e.g. HTML) and the source text is provided for editing? Because if we do, we need an equivalent of source for all the rich text fields (for example summary and our own description), and we need to decide whether to use summary at all. Issue #11 has related discussion.

Hmmm here's a quick summary of the open questions:

  • Do we want to support markup for ticket/MR/CI/kanban/whatever titles? On one hand, it seems that forges and ticket trackers use only plain text, with GitLab auto-detecting links in it but that may be negligible, on the other hand it may be something that makes sense in general and not inherently impossible/wrong
  • Do we want to use summary at all for anything at all in ForgeFed

After we answer those, we have more:

  • For plain text, standard (AP) name or external (DC) title
  • For markup, summary or some new property? content is problematic because it's often not the actual primary content of the object, should we use it anyway?
  • For markup, if we didn't pick content, how is the CommonMark source provided?
> "name" and "content" or "description" should cover any case We need to be sure we want plain text. It seems to be what happens in reality, even web based and wiki based ticket trackers seem to use plain text there, but if there's any reason that someone would start supporting even little markup in titles, that's a point for `summary` or something else that is HTML. The examples in the AP spec use `summary` for object descriptions, so it's something that AP implementations may do. > I would simply define plain text everywhere, or maybe something standard like commonmark Sure, me too, but remember we aren't just defining: We're modeling something to suit the real world situation, which includes both potential ForgeFed implementations, and everything else that uses ActivityPub: - If we go with plain text, we can just use `name` for the user entered title (or the Dublin Core `title`, but either way, no big dilemma here) - If we go with CommonMark, we need to deal with `summary` and `source`. In ActivityPub there's a single property for the source of the rendered HTML, and that's `source`. And it's only for `content`. So I find myself asking, do we follow the AP convention where rich content is federated in rendered form (e.g. HTML) and the source text is provided for editing? Because if we do, we need an equivalent of `source` for all the rich text fields (for example `summary` and our own `description`), and we need to decide whether to use `summary` at all. Issue #11 has related discussion. Hmmm here's a quick summary of the open questions: - Do we want to support markup for ticket/MR/CI/kanban/whatever titles? On one hand, it seems that forges and ticket trackers use only plain text, with GitLab auto-detecting links in it but that may be negligible, on the other hand it may be something that makes sense in general and not inherently impossible/wrong - Do we want to use `summary` at all for anything at all in ForgeFed After we answer those, we have more: - For plain text, standard (AP) `name` or external (DC) `title` - For markup, `summary` or some new property? `content` is problematic because it's often not the actual primary content of the object, should we use it anyway? - For markup, if we didn't pick `content`, how is the CommonMark source provided?
Sign in to join this conversation.
Loading...
Cancel
Save
There is no content yet.