Visualize contribution in commit messages


(Mathias Schreiber) #1

Discussion Topic

In order to give credit to everybody involved in a commit I suggest a change to the commit message format (incl. its corresponding hook).
This way we can give credit to the people that reported an issue, did conceptual work, designed things, mentored a new contributor and more.
Opposed to other OSS projects I’d like to advise against adding a percentage to the amount of contribution. First off it just wastes time and secondly every contribution counts, no matter how insignificant it might seem.

New Commit Message Format proposal

[BreakingIndicator][PatchTag] Title

Verbose message about the change.
* Bullet points are okay, too
* An asterisk is used for the bullet, it can be preceded by a single space.
  This format is rendered correctly by Forge (redmine)
* Use a hanging indent

Resolves: #IssueNumber
Related: #IssueNumber
Releases: [ReleaseTags]

Reporter:  Jane Doe
Concept:   Rachel Foucard
UX:        Benji Kott
GFX:       Luis Pato
GFX:       Marco Christian Krenn
Mentor:    -
Proofread: Tom Warwick
Reviewer:  Oliver Klee
Reviewer:  Rens Admiraal

Change-Id: I<some string generated by the git commit-msg hook>

As you can see, lines can exist multiple times in case more people participated in the patch.
I’m not 100% sure about the Reviewer thing, because Gerrit should take care of that.

Impact

  • Adjust ContributionGuide
  • Adjust pre-commit hook

Possible Migrations

  • before merging an “old” patchset the merging person will ask around to find people involved in the patch. Yes, it’s overhead, but I’d argue it’s worth it.

Pro

  • Show some respect and give credit where credit is due

Con

  • Time spent finding people who were involved.

Remarks and notes

Add everything from the discussion that does not fit other categories.

Organizational

Topic Initiator: Mathias Schreiber
Topic Mentor: Susanne Moog


Development Tools and Future of Forge
(Richard Haeser) #2

I think this is a nice thing to do! The reviewers are already added by Gerrit isn’t it: https://github.com/TYPO3/TYPO3.CMS/commit/a0d0752efd10f53ebac60d8a38e9b33f14a89c75

Maintaining reviewers in the commit message by hand is a little too time-consuming I think, especially when it is done by Gerrit already.


(Mathias Schreiber) #3

edit//

  • added Proofreading line

(Tymoteusz Motylewski) #4

I agree that it would be great to give more credit to contributors, however I’m afraid this solution will bring much overhead to every patch made if it requires manual work. Additionally it will cause endless discussion like “why my name was not in the commit message”.

So I’m ok if we make it an automatic process which doesn’t require manual action. Otherwise I’m against it, and would rather spend time on finding other ways to give credit, e.g. posting picture with few sentences about every first -time contributor every month on typo3.org.

Commit messages are sth only devs (who alre already deep in the project) see and care about. All other people (including potential new contributors) don’t read through commit details.


(Stefan Neufeind) #5

How about people involved in a patch/review add themselves as reviewers if interested and contribute “by reading” or the like? This way the reviewers-lines would suffice.

I also think that adding more complexity here is unrealistic. For certain limited cases when it’s still needed to give a special credit you can add a person to the commit-message manually imho. (like “based on a design by …” or so).

I’d appreciate comments from people actually targeted by the proposed change. Maybe I’m underestimating the importence for them to be named more often/prominent. That might well be.


(Helmut Hummel) #6

While I love the idea to credit all people involved in a change, I also fear that adding it to the commit message is quite some overhead.

Since the issue number is part of the commit message anyway, I would suggest to add this information to Forge and add a issue template that has these fields in there already so that they can be filled out optionally.

We could then automate the extraction of this information into some ChangeLog or contributors list.

When thinking about other workflows, like Gitlab or Github, I also believe such info would rather belong in the pull request than the commit message itself.


(Markus Klein) #7

I think appreciation should be shown on a more public place than the commit message, as noted already.
IMO the commit msg basically says “who is to punish if this thing did something bad”.

I would also suggest to embrace forge a bit more for such purposes, besides that an issue template would be very very helpful in general.


(Mathias Schreiber) #8

The plan is to have a source for contribution that follows the following features:

  • reliable
  • watched by a lot of people
  • high chance of quality
  • high probability of contribution
  • little room for errors

It is a data source that in return powers content-carriers like:

  • monthly blogpost on typo3.com
  • karma calculator on typo3.org
  • partner commitment calculator on typo3.com
  • TYPO3 release notes
  • TYPO3 release news
  • TYPO3 newsletter

Gerrit seems to be the only source that actually qualifies for it because people care for a properly formatted message.

Sidenote: afaik issue templates on forge will not be available short- to mid-term.
Apart from that enforcing the template cannot be done (at least that was not possible the last time I used issue templates in redmine.
If we decide for a non-testable, brittle way, we would not need to change the workflow because then you could just add the names to the release notes manually.

The overhead is something we’d need to live with, if we want to credit (and more importantly encourage) new people to contribute.
Things won’t get done by themselves :slight_smile:


(Jigal Van Hemert) #9

We can do that. I expect that most patches will only have a reporter line (reviewers are added by Gerrit) but more complex changes can give credit to more people and roles.


(Markus Klein) #10

Sidnote on the proposed commit msg: Don’t know if this is relevant, but to current knowledge the meta-data block in the commit message shall be one paragraph only and the last one. The current proposal ships 3 of them.


(Stefan Busemann) #11

I think visualize contribution is one part of enlarging contribution. For me this one possibility to give more people credit for their work, which normally stay invisible.

We could use these data also for our my.typo3.org project. Here it is planned to visualize contribution for single members of the community (have personal profile page and show the contribution) and association members (companies), where the contribution of single persons is cumulated.


(Georg Ringer) #12

I would love to have give those users more credit but I am not sure if the commit message is the right place.

Better proposal: Do it like the the Developer Apprecation Day (https://typo3.com/blog/march-2018-developer-appreciation-day-dad/) and collect the data via forger / API and make a great visualization


(Mathias Schreiber) #13

I really don’t mean to be bitchy, but take a guess where forger gets its data from :wink:


Change List of Changes for TYPO3 release to include links to commit msg on github
(Georg Ringer) #14

I of course know that but I am more a fan of having such stuff as for coreteam contributions … in the long run something like gamifcation could be done like: when your first 10 contributions are merged, you will get a tshirt


(Richard Haeser) #15

I think it is just a little extra effort to give (especially less frequent) contributors the recognition they deserve.

Is it possible by the pre-commit-hook to check the redmine API to get the Reporter automatically? That’s one thing less to do by hand (although it is the easiest one).


(Rens Admiraal) #16

I like it, also because the commit message is probably early enough after doing the real work to remember the contributors. But I do see the point @helhum makes about “what to do if you forget”, because merged is merged… What about merging them with the people which are linked to the issue?


(Sybille Peters) #17

I like the general idea but agree if it’s too much work and can’t be automated, we should not do it. It will sometimes be really hard to determine who and what has contributed to some patch.

So, what can be automated is the people who contributed to the issue on forge. The issue id is already in the commit msg. But I wouldn’t put the all people in the commit msg. That can be retreived at a later point from the issue id.

I have strong objections against any remote API calls from the commit-msg hook. The whole idea of git is that you can work and commit remotely without an internet connection. Anything that might disrupt the development workflow should be considered very carefully.

There were some good ideas here and you already have implemented some: The Developer Appreciation page for example. I would like to see the people who contributed to forge and to the documentation on there too.

I would love to vote for some of the new ideas.

And, I would like to second an idea: Give-aways for contributors. If you don’t have enough, do a raffle.

I don’t know what contributors would want, but I know what I would want: One poster either of the 9.1.0 and 9.2.0 image and slogan (“love at first site” and 'let’s go site-seeing") or all coming releases in limited edition and signed by the core team (or just one person to be realistic). On oversized postcard would do as well.

For others, it might be a very nerdy poster of their first commit message for TYPO3. Who knows? (Everyone already has dozens of t-shirts from barcamps, that’s why posters. And, they’re cooler).


(Riccardo De Contardi) #18

agree with the idea, but I think that it should be automated, too othewise it could become too difficult or too error-prone


(Alexander Opitz) #19

Only the reviewers of the last patch get mentioned in the commit message. But sometimes there is a small last change which is reviewed fast from others to get the change in.


(Mathias Schreiber) #20

I would like to ask one favour by every member of the coreteam (as in: those people who merge stuff):
Take 10 minutes and look through your last 20 merges.
How often would you actually need to spend time to set those values?
In case you need to… how long would it take you?

I just did this exercise and realised that most patches don’t even need to give credit to someone other than the reporter and me, so maybe you’re not even “affected” by this proposal.

In regards to the “what if we forgot someone?” argument.
I think it’s valid, but not critical, though.
We forgot to add someone, so be it. It’s a fair mistake and as long as we all agree to strive for giving credit to those involved I don’t see an issue with that.
If you feel offended by someone making a mistake there’s a lot more wrong with you than we could possibly ever fix in this community anyways.

In the end, the time spent is an investment.
It’s an investment in giving credit where credit is due.
It’s an investment in an open, respectful community.
It’s an investment in encouraging more people to contribute.
It’s an investment in creating a more diverse community.

In short: it’s an investment in TYPO3.