#24 Properties for commit message

Open
opened 11 months ago by fr33domlover · 4 comments

How to specify the commit message in ActivityPub?

(1) Unified or split

Should the entire text, i.e. title and description, go into a single string, or should they be separate?

(Client UI would very likely want to be able to have them split, display one without the other, display them in different styles, etc.)

(2) Property for title

Which property to use for the commit message's title? There's name which is plain-text but is a commit title really the name of the commit? There's also summary which would be good, but it's HTML. Reasonable if we use summary in other places already, such as for Ticket titles and MR titles and so on.

(3) Property for description

If using separate properties for title and description, which property to use for the description?

If we use summary for title, then using plain-text for description would be weird. Should probably either use content or an embedded object with a content property, and source set to the exact original plain-text message.

Another option is to use entirely new custom properties, but is there really a good reason to deviate from the standard properties?

Thoughts / ideas / proposals?

NOTE: This isn't git specific, so when you think about this stuff, consider other VCSs too such as Mercurial, Darcs, Monotone, etc.

Forum topic

How to specify the commit message in ActivityPub? # (1) Unified or split Should the entire text, i.e. title and description, go into a single string, or should they be separate? (Client UI would very likely want to be able to have them split, display one without the other, display them in different styles, etc.) # (2) Property for title Which property to use for the commit message's title? There's `name` which is plain-text but is a commit title really the *name* of the commit? There's also `summary` which would be good, but it's HTML. Reasonable if we use `summary` in other places already, such as for `Ticket` titles and MR titles and so on. # (3) Property for description If using separate properties for title and description, which property to use for the description? If we use `summary` for title, then using plain-text for description would be weird. Should probably either use `content` or an embedded object with a `content` property, and `source` set to the exact original plain-text message. Another option is to use entirely new custom properties, but is there really a good reason to deviate from the standard properties? Thoughts / ideas / proposals? NOTE: This isn't git specific, so when you think about this stuff, consider other VCSs too such as Mercurial, Darcs, Monotone, etc. [Forum topic](https://talk.feneas.org/t/properties-for-commit-message/81)
fr33domlover commented 11 months ago
Collaborator

Update: In Darcs, a patch has a name and a description. So it may be okay to use the name property and a plain-text content. The question is, do we want to have built-in HTML for them like for ticket title and description etc.?

Update: In Darcs, a patch has a **name** and a **description**. So it may be okay to use the `name` property and a plain-text `content`. The question is, do we want to have built-in HTML for them like for ticket title and description etc.?
fr33domlover commented 11 months ago
Collaborator

Update: I couldn't find much reference to commit messages being Markdown or HTML. githu8 and Gitea seem to display commit messages as plain text. I don't know if there's any harm in providing an HTML version in addition to the plain text, but it can be awkward if it's not obvious how the HTML was produced, and it doesn't seem like there's actual usage of such HTML rendering. Feels safer to me to go with plain text, for both title and description.

Update: I couldn't find much reference to commit messages being Markdown or HTML. githu8 and Gitea seem to display commit messages as plain text. I don't know if there's any harm in providing an HTML version in addition to the plain text, but it can be awkward if it's not obvious how the HTML was produced, and it doesn't seem like there's actual usage of such HTML rendering. Feels safer to me to go with plain text, for both title and description.
zPlus commented 6 months ago
Owner

Commits in Git do not have a title, nor have other VCSes such as CVS and SVN, as far as I know. Perhaps then we can define a name property and leave it out to each actor to decide what to put in there.

Both name and content should be plain text imo.

Commits in Git do not have a title, nor have other VCSes such as CVS and SVN, as far as I know. Perhaps then we can define a `name` property and leave it out to each actor to decide what to put in there. Both `name` and `content` should be plain text imo.
fr33domlover commented 4 months ago
Collaborator

Hmmm last thing before I close this: Shall we use content directly, or put it inside a custom description property? i.e. these two examples:

Directly:

{
          "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://forgefed.peers.community/ns"
          ],
          "id": "https://example.dev/alice/myrepo/commits/109ec9a09c7df7fec775d2ba0b9d466e5643ec8c",
          "type": "Commit",
          "context": "https://example.dev/alice/myrepo",
          "attributedTo": "https://example.dev/bob",
          "committedBy": "https://example.dev/alice",
          "hash": "109ec9a09c7df7fec775d2ba0b9d466e5643ec8c",
          "created": "2019-07-11T12:34:56Z",
          "committed": "2019-07-26T23:45:01Z",
          "name": "Add an installation script, fixes issue #89",

          "mediaType": "text/plain",
          "content": "It's about time people can install on their computers!"
}

Inside description property:

{
          "@context": [
              "https://www.w3.org/ns/activitystreams",
              "https://forgefed.peers.community/ns"
          ],
          "id": "https://example.dev/alice/myrepo/commits/109ec9a09c7df7fec775d2ba0b9d466e5643ec8c",
          "type": "Commit",
          "context": "https://example.dev/alice/myrepo",
          "attributedTo": "https://example.dev/bob",
          "committedBy": "https://example.dev/alice",
          "hash": "109ec9a09c7df7fec775d2ba0b9d466e5643ec8c",
          "created": "2019-07-11T12:34:56Z",
          "committed": "2019-07-26T23:45:01Z",
          "name": "Add an installation script, fixes issue #89",

          "description": {
              "mediaType": "text/plain",
              "content": "It's about time people can install on their computers!"
          }
}
Hmmm last thing before I close this: Shall we use `content` directly, or put it inside a custom `description` property? i.e. these two examples: Directly: ``` { "@context": [ "https://www.w3.org/ns/activitystreams", "https://forgefed.peers.community/ns" ], "id": "https://example.dev/alice/myrepo/commits/109ec9a09c7df7fec775d2ba0b9d466e5643ec8c", "type": "Commit", "context": "https://example.dev/alice/myrepo", "attributedTo": "https://example.dev/bob", "committedBy": "https://example.dev/alice", "hash": "109ec9a09c7df7fec775d2ba0b9d466e5643ec8c", "created": "2019-07-11T12:34:56Z", "committed": "2019-07-26T23:45:01Z", "name": "Add an installation script, fixes issue #89", "mediaType": "text/plain", "content": "It's about time people can install on their computers!" } ``` Inside `description` property: ``` { "@context": [ "https://www.w3.org/ns/activitystreams", "https://forgefed.peers.community/ns" ], "id": "https://example.dev/alice/myrepo/commits/109ec9a09c7df7fec775d2ba0b9d466e5643ec8c", "type": "Commit", "context": "https://example.dev/alice/myrepo", "attributedTo": "https://example.dev/bob", "committedBy": "https://example.dev/alice", "hash": "109ec9a09c7df7fec775d2ba0b9d466e5643ec8c", "created": "2019-07-11T12:34:56Z", "committed": "2019-07-26T23:45:01Z", "name": "Add an installation script, fixes issue #89", "description": { "mediaType": "text/plain", "content": "It's about time people can install on their computers!" } } ```
Sign in to join this conversation.
Loading...
Cancel
Save
There is no content yet.