Property for titles

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 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
  • 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. Which makes me wonder if summary was defined with activities in mind (since they mostly don’t get edits and don’t need summary editing).

Thoughts? :slight_smile:

AFAIK summary is plain text only as well. It is used this way at the moment. I would always suggest name for the title. The summary is meant as a summary, means a little bit longer text as the title. For rich text you should use content.

BTW: When you use custom fields, please consider this in your JSON structure. To make a valid JSON-LD, you need some namespace.

I would avoid encouraging rich text in summary or titles. It sounds like a mess waiting to happen. Of course this is mostly a UX thing, not really a protocol thing and I’m not sure the ForgeFed spec needs to go into detail like this?

For example Socialhome runs a HTML/JS/CSS cleaner on all text fields for security, whitelisting only certain tags with content only.

@heluecht, technically summary is HTML on the spec level, even if right now people happen to put only plain text there. Have to take that into account in the decision. But good point about summary being longer than a title, that’s a point in favor of name.

@jaywink, I’m trying to make the ForgeFed core specs flexible, but there are things I can’t avoid, such as to say which types and properties people should use to represent forge related objects as ActivityPub JSON-LD. I’m okay with assuming plain text in titles, it seems to be what everyone is doing anyway, but I want to be sure we want to guide spec implementors in that direction. I mean, what if there’s some forge I didn’t notice, that allows some basic Markdown features in issue titles? Is there a good reason nobody is doing that? Obviously the spec could mention properties for both cases (plain text and HTML) but that means implementations would end up being ready for both (so might as well just go with HTML) or it would just cause confusion.

Does everyone feel sure about using name (i.e. plain text) for titles? Is the possibility of bits of markup in titles too unreasonable to be considered, is there no forge or ticket tracker that does that? If that’s the case, help me be convinced and I’ll go with name ^ _ ^

Then they will do that and anyone who doesn’t support it shows a cleaned version or a version not rendered. You wont be able to pre-calculate all possible compatibility issues because that is impossible. People build different types of platforms for a reason. It’s what the federated web is by nature - compatible but incompatible, and no amount of spec work will change that. And if it did it would be terrible, imho, since having differences in features is richness.

Wise words :slight_smile: hmmm but things would be more complicated than that if we picked plain text:

  • When authoring objects, implementations supporting rich text titles would have to provide a plain text version in the name property
  • When doing federated updates that edit the object’s title, implementations would edit the name but leave the real rich-text source (e.g. Markdown) and HTML untouched, because they don’t understand that property

In other words, once everyone assumes plain text, having real rich text support requires everyone coordinating and implementing it together. We have 2 chances to do that:

  1. Put it in the spec. Pro: World will be ready for rich text titles if they arise. Con: Makes everyone implement something that doesn’t seem to be used anywhere in reality.
  2. Not put it in the spec. Pro: Everyone already uses and assumes plain text in titles, so it’s trivial to just keep using plain text. Con: If a decision arises to support rich text, it would require the community to agree on how to do this.

Hmmm when viewed like this, it seems a bit silly to force everyone to support rich text titles in advance ^ _ ^ I guess we can use name for this, and if the need for rich text titles ever arises, switch to something else.

1 Like