Commit comments - call for opinions

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

Commit comments - call for opinions

Tobias Dammers
Dear all,

So far, we had a feature in Trac where git commit messages mentioning a
ticket would automatically be copied into a comment on that commit. See,
for example, this comment:

https://ghc.haskell.org/trac/ghc/ticket/13615#comment:47

GitLab does things slightly differently. It has "live" git repository
information available, and rather than the relatively static comment
list we see in Trac, it synthesizes a "timeline" style list of events
relevant to an issue, which includes comments ("notes"), but also issue
status updates, git commits, and other things. So when a commit mentions
a GitLab issue, then GitLab will insert a link to that commit into the
issue's event timeline.

This means that in principle, copying commit messages into notes would
be redundant, and we initially decided to ignore commit comments during
the Trac/GitLab migration. However, it also means that the issue
timeline will no longer display the actual commit message anymore, just
a link to the commit ("@username mentioned this issue in commit
1234beef" or similar). So what used to be a narrative that you could
read top-down to retrace the issue's history is now a bit more
scattered.

Now, the ideal solution would be for GitLab to instead display the full
commit message, but I don't see this happening anytime soon, because it
would require a patch to GitLab itself. So we're left with two options:

a) Import commit comments as notes, duplicating the commit message into
the note, and having both the full commit note and a hyperlinked commit
reference in the issue timeline.

b) Don't import commit comments as notes, just rely on GitLab to insert
the hyperlinked commit reference.

If any of you have any preference either way, please do tell.

Thanks!

--
Tobias Dammers - [hidden email]
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

RE: Commit comments - call for opinions

GHC - devs mailing list
|  GitLab does things slightly differently. It has "live" git repository
|  information available, and rather than the relatively static comment list
|  we see in Trac, it synthesizes a "timeline" style list of events relevant
|  to an issue, which includes comments ("notes"), but also issue status
|  updates, git commits, and other things.

Can you show an example of such a time-line? Where is it displayed?  The "Discussion" tab perhaps?

Personally I like what we are doing now, with the commit message inline. Clicking links to see useful information gets in the way.  (I'm not sure if even the title/author/date of the commit are displayed.)

|  a) Import commit comments as notes, duplicating the commit message into
|  the note, and having both the full commit note and a hyperlinked commit
|  reference in the issue timeline.

I'm in favour of this.  It just preserves history and doesn't commit us for the future.

One more question: currently the commit appears as a comment in every Trac ticket that is mentioned in the text of the commit message.  That's _really_ useful, because it signals (in those related tickets) that there's a relevant commit to watch out for.  Will it continue to be the case?

Simon

|  -----Original Message-----
|  From: ghc-devs <[hidden email]> On Behalf Of Tobias Dammers
|  Sent: 07 February 2019 08:48
|  To: GHC Devs <[hidden email]>
|  Subject: Commit comments - call for opinions
|  
|  Dear all,
|  
|  So far, we had a feature in Trac where git commit messages mentioning a
|  ticket would automatically be copied into a comment on that commit. See,
|  for example, this comment:
|  
|  https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fghc.has
|  kell.org%2Ftrac%2Fghc%2Fticket%2F13615%23comment%3A47&amp;data=02%7C01%7C
|  simonpj%40microsoft.com%7C4e4e4de2a28141c38bfd08d68cd9015b%7C72f988bf86f1
|  41af91ab2d7cd011db47%7C1%7C0%7C636851260994463920&amp;sdata=JpLtBith2iW2N
|  fbYdZOt7dsjhKm1Ram7QCgR7aeiVUs%3D&amp;reserved=0
|  
|  GitLab does things slightly differently. It has "live" git repository
|  information available, and rather than the relatively static comment list
|  we see in Trac, it synthesizes a "timeline" style list of events relevant
|  to an issue, which includes comments ("notes"), but also issue status
|  updates, git commits, and other things. So when a commit mentions a
|  GitLab issue, then GitLab will insert a link to that commit into the
|  issue's event timeline.
|  
|  This means that in principle, copying commit messages into notes would be
|  redundant, and we initially decided to ignore commit comments during the
|  Trac/GitLab migration. However, it also means that the issue timeline
|  will no longer display the actual commit message anymore, just a link to
|  the commit ("@username mentioned this issue in commit 1234beef" or
|  similar). So what used to be a narrative that you could read top-down to
|  retrace the issue's history is now a bit more scattered.
|  
|  Now, the ideal solution would be for GitLab to instead display the full
|  commit message, but I don't see this happening anytime soon, because it
|  would require a patch to GitLab itself. So we're left with two options:
|  
|  a) Import commit comments as notes, duplicating the commit message into
|  the note, and having both the full commit note and a hyperlinked commit
|  reference in the issue timeline.
|  
|  b) Don't import commit comments as notes, just rely on GitLab to insert
|  the hyperlinked commit reference.
|  
|  If any of you have any preference either way, please do tell.
|  
|  Thanks!
|  
|  --
|  Tobias Dammers - [hidden email]
|  _______________________________________________
|  ghc-devs mailing list
|  [hidden email]
|  https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fmail.has
|  kell.org%2Fcgi-bin%2Fmailman%2Flistinfo%2Fghc-
|  devs&amp;data=02%7C01%7Csimonpj%40microsoft.com%7C4e4e4de2a28141c38bfd08d
|  68cd9015b%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636851260994473914
|  &amp;sdata=sybIa7Fec76lod2d65Wc2IN187WGG3LjI2ydjpsFJF0%3D&amp;reserved=0
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Commit comments - call for opinions

Matthew Pickering
In reply to this post by Tobias Dammers
I am in favor of option b) as it fits in better with the "gitlab way
of things". If we are to use gitlab then we should use it as it's most
intended rather than trying to retrofit trac practices which have
accrued over many years.

Adding commits as comments is just a hack in trac to work around
missing native support for the fundamental operation of linking a
commit to.

I don't really see that it is much more inconvenient to click on a
link to see the commit, the hash can be hovered over to see the commit
title.

Clicking on the link will then also give the full commit message but
also the full set of changes as well which is probably more useful.

Cheers,

Matt

On Thu, Feb 7, 2019 at 8:48 AM Tobias Dammers <[hidden email]> wrote:

>
> Dear all,
>
> So far, we had a feature in Trac where git commit messages mentioning a
> ticket would automatically be copied into a comment on that commit. See,
> for example, this comment:
>
> https://ghc.haskell.org/trac/ghc/ticket/13615#comment:47
>
> GitLab does things slightly differently. It has "live" git repository
> information available, and rather than the relatively static comment
> list we see in Trac, it synthesizes a "timeline" style list of events
> relevant to an issue, which includes comments ("notes"), but also issue
> status updates, git commits, and other things. So when a commit mentions
> a GitLab issue, then GitLab will insert a link to that commit into the
> issue's event timeline.
>
> This means that in principle, copying commit messages into notes would
> be redundant, and we initially decided to ignore commit comments during
> the Trac/GitLab migration. However, it also means that the issue
> timeline will no longer display the actual commit message anymore, just
> a link to the commit ("@username mentioned this issue in commit
> 1234beef" or similar). So what used to be a narrative that you could
> read top-down to retrace the issue's history is now a bit more
> scattered.
>
> Now, the ideal solution would be for GitLab to instead display the full
> commit message, but I don't see this happening anytime soon, because it
> would require a patch to GitLab itself. So we're left with two options:
>
> a) Import commit comments as notes, duplicating the commit message into
> the note, and having both the full commit note and a hyperlinked commit
> reference in the issue timeline.
>
> b) Don't import commit comments as notes, just rely on GitLab to insert
> the hyperlinked commit reference.
>
> If any of you have any preference either way, please do tell.
>
> Thanks!
>
> --
> Tobias Dammers - [hidden email]
> _______________________________________________
> ghc-devs mailing list
> [hidden email]
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Commit comments - call for opinions

Tobias Dammers
In reply to this post by GHC - devs mailing list
On Thu, Feb 07, 2019 at 09:22:28AM +0000, Simon Peyton Jones wrote:
> |  GitLab does things slightly differently. It has "live" git repository
> |  information available, and rather than the relatively static comment list
> |  we see in Trac, it synthesizes a "timeline" style list of events relevant
> |  to an issue, which includes comments ("notes"), but also issue status
> |  updates, git commits, and other things.
>
> Can you show an example of such a time-line? Where is it displayed?
> The "Discussion" tab perhaps?

The timeline I'm talking about is simply the "activity list" right below
the issue body. I did just realize however that our gitlab instance
doesn't currently display any commits mentioning the issue. I haven't
dug into it very deeply, but the research I've done so far suggests that
this should in fact happen; the GitLab documentation explicitly says
that mentioning issues in commits will link the two together, and this
should generate an entry in the activity list. I can imagine, however,
that this only works if the commit gets pushed after the issue has been
created, which means we would have to somehow cater for this as part of
the import. I will investigate further. If anyone happens to know
whether this is indeed the cause, please do tell.

> Personally I like what we are doing now, with the commit message
> inline. Clicking links to see useful information gets in the way.
> (I'm not sure if even the title/author/date of the commit are
> displayed.)

If and when that feature works, it will display:

- Commit author
- Commit hash
- Commit date (though possibly mangled into a "humane" format, e.g. "6
  hours ago").

E.g.:

"Simon Peyton-Jones @simonpj mentioned in commit abc123 2 months ago"

The commit message is not included however.

> |  a) Import commit comments as notes, duplicating the commit message into
> |  the note, and having both the full commit note and a hyperlinked commit
> |  reference in the issue timeline.
>
> I'm in favour of this.  It just preserves history and doesn't commit
> us for the future.

> One more question: currently the commit appears as a comment in every
> Trac ticket that is mentioned in the text of the commit message.
> That's _really_ useful, because it signals (in those related tickets)
> that there's a relevant commit to watch out for.  Will it continue to
> be the case?

According to the GitLab documentation, mentioning any issue in any
commit (or merge request, even) will link the two, so yes, you can
absolutely mention multiple issues in one commit, and they will all be
linked. GitLab does not support duplicating the text into the issue
timeline verbatim however; if we want that even for future commits, then
we will have to come up with some sort of hack (either patch GitLab to
do it on the fly, or run some external bot that injects them as plain
notes).


> |  -----Original Message-----
> |  From: ghc-devs <[hidden email]> On Behalf Of Tobias Dammers
> |  Sent: 07 February 2019 08:48
> |  To: GHC Devs <[hidden email]>
> |  Subject: Commit comments - call for opinions
> |  
> |  Dear all,
> |  
> |  So far, we had a feature in Trac where git commit messages mentioning a
> |  ticket would automatically be copied into a comment on that commit. See,
> |  for example, this comment:
> |  
> |  https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fghc.has
> |  kell.org%2Ftrac%2Fghc%2Fticket%2F13615%23comment%3A47&amp;data=02%7C01%7C
> |  simonpj%40microsoft.com%7C4e4e4de2a28141c38bfd08d68cd9015b%7C72f988bf86f1
> |  41af91ab2d7cd011db47%7C1%7C0%7C636851260994463920&amp;sdata=JpLtBith2iW2N
> |  fbYdZOt7dsjhKm1Ram7QCgR7aeiVUs%3D&amp;reserved=0
> |  
> |  GitLab does things slightly differently. It has "live" git repository
> |  information available, and rather than the relatively static comment list
> |  we see in Trac, it synthesizes a "timeline" style list of events relevant
> |  to an issue, which includes comments ("notes"), but also issue status
> |  updates, git commits, and other things. So when a commit mentions a
> |  GitLab issue, then GitLab will insert a link to that commit into the
> |  issue's event timeline.
> |  
> |  This means that in principle, copying commit messages into notes would be
> |  redundant, and we initially decided to ignore commit comments during the
> |  Trac/GitLab migration. However, it also means that the issue timeline
> |  will no longer display the actual commit message anymore, just a link to
> |  the commit ("@username mentioned this issue in commit 1234beef" or
> |  similar). So what used to be a narrative that you could read top-down to
> |  retrace the issue's history is now a bit more scattered.
> |  
> |  Now, the ideal solution would be for GitLab to instead display the full
> |  commit message, but I don't see this happening anytime soon, because it
> |  would require a patch to GitLab itself. So we're left with two options:
> |  
> |  a) Import commit comments as notes, duplicating the commit message into
> |  the note, and having both the full commit note and a hyperlinked commit
> |  reference in the issue timeline.
> |  
> |  b) Don't import commit comments as notes, just rely on GitLab to insert
> |  the hyperlinked commit reference.
> |  
> |  If any of you have any preference either way, please do tell.
> |  
> |  Thanks!
> |  
> |  --
> |  Tobias Dammers - [hidden email]
> |  _______________________________________________
> |  ghc-devs mailing list
> |  [hidden email]
> |  https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fmail.has
> |  kell.org%2Fcgi-bin%2Fmailman%2Flistinfo%2Fghc-
> |  devs&amp;data=02%7C01%7Csimonpj%40microsoft.com%7C4e4e4de2a28141c38bfd08d
> |  68cd9015b%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C636851260994473914
> |  &amp;sdata=sybIa7Fec76lod2d65Wc2IN187WGG3LjI2ydjpsFJF0%3D&amp;reserved=0

--
Tobias Dammers - [hidden email]
_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
Reply | Threaded
Open this post in threaded view
|

Re: Commit comments - call for opinions

Ben Gamari-2
In reply to this post by Matthew Pickering
Matthew Pickering <[hidden email]> writes:

> I am in favor of option b) as it fits in better with the "gitlab way
> of things". If we are to use gitlab then we should use it as it's most
> intended rather than trying to retrofit trac practices which have
> accrued over many years.
>
> Adding commits as comments is just a hack in trac to work around
> missing native support for the fundamental operation of linking a
> commit to.
>
Well, I'm not sure that's *entirely* true.

> I don't really see that it is much more inconvenient to click on a
> link to see the commit, the hash can be hovered over to see the commit
> title.
>
I can see Simon's point here; Trac tickets generally tell a story,
consisting of both comments as well as commit messages. It's not clear
to me why the content of the former should be more visible than that of
the latter. They both tell equally-important parts of the story.

Cheers,

- Ben


_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

signature.asc (497 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Commit comments - call for opinions

Richard Eisenberg-4
I personally prefer seeing the whole commit message, if only because including it is more prominent than just a mention. Commits are really important, and should be made to stand out beyond just a mention. Not sure if this is worth yet more custom tooling, though.

Richard

> On Feb 8, 2019, at 7:04 PM, Ben Gamari <[hidden email]> wrote:
>
> Matthew Pickering <[hidden email]> writes:
>
>> I am in favor of option b) as it fits in better with the "gitlab way
>> of things". If we are to use gitlab then we should use it as it's most
>> intended rather than trying to retrofit trac practices which have
>> accrued over many years.
>>
>> Adding commits as comments is just a hack in trac to work around
>> missing native support for the fundamental operation of linking a
>> commit to.
>>
> Well, I'm not sure that's *entirely* true.
>
>> I don't really see that it is much more inconvenient to click on a
>> link to see the commit, the hash can be hovered over to see the commit
>> title.
>>
> I can see Simon's point here; Trac tickets generally tell a story,
> consisting of both comments as well as commit messages. It's not clear
> to me why the content of the former should be more visible than that of
> the latter. They both tell equally-important parts of the story.
>
> Cheers,
>
> - Ben
>
> _______________________________________________
> ghc-devs mailing list
> [hidden email]
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs

_______________________________________________
ghc-devs mailing list
[hidden email]
http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs