Simplify agreed commit format and comply with Conventional commits spec

@fjgarlin, thanks for pulling this together.

I am all for a simple solution, which the proposed resolution is. And I prefer 'By" instead of "Authored-by".

Also, we seem to be “linking” (again?) the commit message with the credits, when these two things are (and should be) independent.

Where is this happening, on an issue?

Discussed on slack and I'm +1 for the simplification. The original proposal is way too time consuming to make it accurate.

It already takes quite a lot of time to sort out issue credit relative to everything else on an issue, at least on any issue with more than five people involved. Reviewer vs author is also often blurred - if someone does deep reviews, possibly with gitlab suggestions, vs someone making a couple of quick changes to resolve feedback.

So agreed with keeping this as simple as possible.

This is quite a small change, even though the original format change took years to sort out, so I'm going to move it to RTBC. We're not in a position to actually use the format yet, so agreeing to change it just means changing what we'll eventually be able to use once we move to gitlab issues, although it will impact some contrib modules quicker.

These lines are officially called "trailers" and I think there are some vague standards for them.

GitLab apparently generates certain forms of these, though the docs are sparse: https://docs.gitlab.com/user/project/repository/signed_commits/web_commits/

The GitLab UI also parses and uses the trailers for display: https://gitlab.com/gitlab-org/gitlab-foss/-/issues/31640

GitHub supports at least Co-authored-by: https://docs.github.com/en/pull-requests/committing-changes-to-your-proj...

Would it be helpful for future git archaelogy if we used a somewhat supported standard here? I propose that we use Co-authored-by for all roles, and include the no-reply unique identifier, to simplify the administrivia while allowing existing UIs to display this data. Given the existing message uses "by" for all roles this is not really much different to me, just in an expanded and more machine-readable format.

FWIW WordPress's Gutenberg repo also uses Co-authored-by to credit all contributors to a PR: https://make.wordpress.org/core/2024/02/01/new-commit-message-requiremen...

Some discussion over there about whether or not to use this, from when it was first proposed: https://make.wordpress.org/core/2022/01/31/ensuring-proper-attribution-f...

As far as I can see this is not a documented standard but the Linux kernel first started using trailers because git does not allow multiple authors in a commit, and over time most projects have settled either on Co-authored-by for everyone, or individually named roles.

Co-authored-by is better than Authored-by but I still prefer the simplicity and less wordy By. For me, it means the same as Co-authored-by.

However, I will support either code>By or Co-authored-by.

Yeah agreed with #11.

@fjgarlin is it possible to add the noreply address by default for each co-author as well? I think that is required for GitLab to link the commits back to users - assuming those addresses are known on the GitLab side, I can't see my GitLab profile directly so not sure if this is set up or not.

I've come here via a link to this issue, currently buried inside a collapsed FAQ item on the new contrib record page (https://new.drupal.org/contribution-record/:id ), which is currently being encouraged to module maintainers.

If you are committing, you are encouraged to use the formatting here.

Is it really safe to recommend people start using a new commit message format if the part about multiple authors is not yet settled? Will issue credit be properly picked up, if the format ends up changing?

I still prefer the simplicity and less wordy By.

If an issue has 20+ authors, then a newline and By: username for each one ends up getting really long itself. If we're back to only showing username instead of username <email>, then maybe we can also go back to a single line format like: By: author1, author2, author3, author4.

Will issue credit be properly picked up, if the format ends up changing?

Issue credit isn't based on the commit log, the canonical source is the Drupal.org issue credit records, these are then used in the UI to generate a commit message. So there's no actual effect on commit credit except how this influences the d.o UI.

The thing that could be broken by more than one commit message format change is other things based on commit log parsing like codeswarm.

Okay, that all makes sense, but now I'm trying to understand whether the (non-canonical, fallible, and potentially inaccurate) author credits in the commit message is intended to serve machines or humans?

Fallible because issue credit can be simply forgotten to be copy/pasted at the time of merge. E.g., clicking the "Merge" button in GitLab without remembering to manually edit the commit message or update the MR title and summary first.
Inaccurate because additional issue credits can be awarded on an issue after the commit is merged.

When I look in git blame, I look for the issue number and the names of who worked on an issue - it gives me quick context about who worked on it which is often useful. I will often still need to copy and paste the issue nid and then take a look to see if there's the discussion of the line I'm interested in, but sometimes seeing whether I worked on the line in question or not is enough too.

These lines are officially called "trailers" and I think there are some vague standards for them.

For reference, git trailer official documentation at git documentation, e.g. man git-interpret-trailers.
ℹ️ I already made a few points in the original issue, that may be relevant here.

As @longwave pointed out in previous comments, GitLab, GitHub and others seem to have come to some level of semi-standardization around the Co-authored-by: username <email> trailer, though this is not official in any way. So if the goal is for getting off the island, I'd go with that. On the other hand, if the goal is to just make the old "byline" info in the git commit message available (and easily human-scannable) for casual users, then a custom By: [username1]\nBy: [username2] is okay and By: [comma-separated list of users] even better, since IDE tools that do inline Git blame popups, like GitLense or Better Git Line Blame (which I use in Cursor) would get vertically truncated for really long multi-line commit messages, making it less scannable.

I think it comes down to what problem we're trying to solve. Since we use GitLab, it seems smart to make the effort and feed 2 birds with 1 scone by going with something that GitLab supports.

From https://gitlab.com/gitlab-org/gitlab-foss/-/issues/31640

Gitlab should recognize Co-Authored-By: [name] <[email]> in the message body, and should display user icons on UI related to the commit

they don't actually link to the user from the commit message, as is suggested here, but they list the co-authors along with the main author in the interface

GitHub does interesting things too to surface co-authors: https://github.blog/news-insights/product-news/commit-together-with-co-a...

If we do not consider "co-authored" as a potential issue with copyright, as mentioned in #3540547-8: Add a UI to change "role" values for each user in the footer, then for me either By, or Co-authored-by looks good. I would not add emails, as discussed above.

Updating the issue summary to reflect that we converged on Co-authored-by

Is there a release notes generator handling the new commit format?

TL;DR: I’d rather have no information than wrong information.
-1 to Co-authored-by, +1 to By.

If my heuristic for automatically differentiating co-authors from reviewers in the other issues (if you push commits to the MR, default to co-author, else, default to reviewer) isn’t feasible for technical reasons and/or we’re worried about people debating it case-by-case, MR suggestions blurring the line, etc, I think I’d prefer just By: . Both for copyright and for honesty, I’d rather not call every participant in an issue / MR a co-author. By is bland and vague, just like we use now, but doesn’t imply everyone wrote the change.

When I was originally spearheading this commit format change for core, I was hoping to use it as an opportunity not just to adopt useful 1-line summaries without an incomprehensible wall of usernames, but also to more accurately reflect the reality of who contributed to the change and how. If we call everyone a co-author, it’s less accurate, not more.

Since doing the most accurate things automatically are revealing some technical hurdles and other resistance, the other approach I keep pondering / suggesting is to put the draft commit message to use in the MR body and/or as another section of the issue template and let folks craft / refine the draft commit message collectively. We already have a culture of encouraging people to keep the issue summary accurate. We already have a “field” in the template to collectively write a release note. However, I know folks don’t always do this. Core committers could start refusing to commit RTBC things if they don’t have this message already written. We do that for CRs and release notes. We’ll delay issues for weeks/months nit picking code comments, but then we leave the urgent task of the Git history entirely up to committers to have to do on their own.

The other option, if relying on MR/issue text isn’t going to fly, would be if the credit UI saved state and we could draft a “better” message via that UI. But that’s probably a whole other can of worms.

If there’s no draft, we need a quick / easy way for committers to get something useful, which is what this issue aims to provide. So if every attempt at reflecting reality is going to be ruled out, I vote for something vague and true, not specific and (partly) false, even if GitLab would provide some limited “magic” automatically if we used Co-authored-by.

Setting needs work as I don't see any discussion about the potential liability for core committers claiming an individual who provided review comments disagreeing with the commit is an 'author' of the commit. This was raised in #3540547-8: Add a UI to change "role" values for each user in the footer. As I am not a lawyer, I would suggest core run this past counsel before using "Co-authored-by:".

Yes using By: breaks 3rd party tooling support (which if I understand correctly was a major reason to migrate to the new standard message format) however misusing Co-authored-by would do the same. Addtionaly we already deviate from the standard in other ways (prefixing the issue ID) which breaks tooling.

I also want to note that #29 echos a similar view I previously posted on Slack, that if maintainers (originally discussing Contrib however equally applies to Core) have a concern about the commit message it can indeed be made a gate for RTBC (although I believe only MR opener and Maintainers can edit a MR message).

even if GitLab would provide some limited “magic” automatically if we used Co-authored-by.

Doesn't GitHub and GitLab need full email addresses for this (that match one of the users emails)? Or are we referring to the fact that GiLab can automatically populate Co-authored-by based on commit authors? If the former we won't really see any magic from any of these proposed methods.

If we need to test any of these ideas we still have https://www.drupal.org/project/test_commit_message we can put some test commits in.

Is there a release notes generator handling the new commit format?

I believe Matt Glaman's Drupal MRN site should support all 3 versions of this (By, Authored-by, and Co-authored-by). Related SLACK thread: https://drupal.slack.com/archives/C1BMUQ9U6/p1756151091432389

Addtionaly some more flexible generators (I'm looking at git-cliff at moment) may be able to do the basic release notes portions as well with customization (not sure how they would handled the attribution being malformed, I suspect ignored).

Setting needs work as I don't see any discussion about the potential liability for core committers claiming an individual who provided review comments disagreeing with the commit is an 'author' of the commit.

People have often asked to not be credited in a given issue, and was solved by not crediting them.
This is not a new problem, and the commit message format or the recent changes in the credit system storage have no effect on this. This isn't a new problem, and shouldn't (and probably cannot) be fixed here.

This is not a new problem, and the commit message format or the recent changes in the credit system storage have no effect on this..

Previous versions did not attempt to claim the individual wrote (part of) the code, as is being done with the proposed change in text to "Co-authored-by".

(From the summary):

Any further modifications can be done after the copy/paste of the suggested message.

This is part of the approach to this whole problem that I find a bit problematic. I’d rather this wasn’t entirely dependent on core conmitters to do manually. That’s already a bottleneck. I’m advocating for a solution where at least subsystem maintainers, if not anyone contributing to an issue, can collectively improve this git history in advance. Committers can always override and further edit before they actually push the commit, but we could lighten the load significantly with a collective solution.

Re emails, usernames, etc: sounds like there are some edge cases where we don’t know everything. But a little work could go a long way to providing as much info as we have in the vast majority of cases, no? Eg if I could set my GitLab email address to match the email address I have my local git configured to use, and I always pushed commits with the same address, everything would Just Work(tm), no? Worst case that someone borked this and the same user had 2 different emails? Big deal, we either see both of them or the last one or whatever. It’s still better than having no way to link anyone to a commit other than the Author.

Drupal core doesn't have access to legal counsel and never has done. I'm surprised I even had to type that sentence as it's so far removed from the reality of core development.

The GPL is explicitly provided with no warranty or liability.

As @penyaskito mentions if someone requests not to be credited on an issue we remove them.

For me 'by' and 'co-authored-by' both imply authorship, just the latter sounds artificially a bit grander.

I personally do not care if we use 'by' or 'co-authored-by' but I do care if improvements to the commit message format and gitlab issues get delayed by bike shedding over entirely hypothetical situations.

I'm all for sinplifying the workflow, co-authored-by should be fine. I do think we are overly complicating things by giving co-authored-by so much extra weight. I think for an oblivious person it really means the same as the old format. "Issue xxxx by bbrala, catch" reads the same. "This issue has come together by these people" as co authored suggests also.

Let's not pick a standard, and then move away from that standard too much just because we can explain the words differently.

Also, wouldn't an possible endgoal be that we generate the commitmessage from gitlab as much as possible? There are variables there to do a lot of heavy lifting.

https://docs.gitlab.com/user/project/merge_requests/commit_templates/

That was also part of my frame of reference when discussing the commit message change. Then we don't need to manually do much, but that does mean, dont invent our own. But I guess that part was not iterated much on (or perhaps even mentioned explicitly enoug).

I personally do not care if we use 'by' or 'co-authored-by' but I do care if improvements to the commit message format and gitlab issues get delayed by bike shedding over entirely hypothetical situations.

+1. This is all GPL and in a community that wants to recognize all the people who contributed to get an issue finished.

I also want to remind us all that that this issue is to tweak the agreement of the original issue because of technical reasons. Let's keep it to that.

Since we're removing email due to technical limitations in IS then, in addition to the other "correctness" arguments made above, it makes sense to NOT use 'Co-authored-by' for the simple reason that the emergent standard expects a username + email in that format.

In #23 my proposal was that if consensus is that we're not trying to satisfy machines and other standards, and instead satisfy humans and the dev community, then I'd propose taking it one single step further than just the technical email limitations written in the issue summary, and make the 'By: ' trailer readable as a single comma-separated list of usernames, which aligns more closely with how we used to do it.

Before:

Issue #999999 by user1, user2, user3, user4, user5, user6, user7, user8, user9: Convert MediaSource plugin discovery to attributes

After:

[#999999] task: Convert MediaSource plugin discovery to attributes

By: user1, user2, user3, user4, user5, user6, user7, user8, user9

Instead of:

[#999999] task: Convert MediaSource plugin discovery to attributes

By: user1
By: user2
By: user3
By: user4
By: user5
By: user6
By: user7
By: user8
By: user9

I didn't see anyone address this point yet and it was the primary point I was trying to make. Sorry for what sounds like it devolved into a bikeshed, but this goes directly to the point of considering how the data is used so we can get the format right once and not change it again for 10+ years.

In my mind, a single byline is human friendly and multiple bylines is definitely not human friendly. A machine (eg drupal-mrn.dev) could parse either format equally well, so I say go for what is more human friendly.

#34 is not bikeshedding over hypotheticals. Without email addresses (even hard-coding the no reply if we have to), it’s going to really be hard for any other tooling to be helpful, or for GitLab to do its own magic. Can we prevent letting perfect be the enemy of good and do a best-effort for emails, even if there are edge cases where it doesn’t work flawlessly?

I wasn’t sold on deviating from conventional commits to put the issue number at the front of the line. My original proposals in the initial issue were all to put the issue number after the colon, as the start of the description, since that’s fully compliant with the standard. So long as we don’t get too creative with the type keywords, and mostly use fix, task and feat, it should still be pretty scannable by humans, and totally readable by tools written for the spec. Even with the issue number the front, they’re not all the same number of digits, so they won’t perfectly line up, anyway.

If you’re looking at a rebase or some other action where you only see the 1-line summaries, it’d be something like:

feat: #12345: How do I log in as admin? Whatever something nice to say
fix: #12346: PHPTemplate download for 4.5.0 Some other important thing
task: [#1234789] Clean up the whatever

Vs.

#12345: How do I log in as admin? feat: Whatever something nice to say
#12346: PHPTemplate download for 4.5.0 fix: Some other important thing
[#1234789] task:  Clean up the whatever

IMHO, the 2nd isn’t fundamentally more scannable by humans, but it’s much less scannable by tools written to support the spec.

Finally, I’m still interested in hearing about a collective solution instead of something committers have to do entirely on their own. I’m sad we’re proposing to simplify this message so much, only to make the bespoke tooling a little easier. I’d rather see about ways to make this whole task part of the work of getting an issue ready to be committed, and then be able to take fully advantage of the improved format for the benefit of our Git history.

Thanks,
-Derek

I'm not sure how a (more) collective solution could work technically. Currently both committers and subsystem maintainers can assign issue credit (hopefully this is the case with the new system) - when this is already done on a complex issue it definitely helps, and is a collective process.

However the commit message itself is automatically generated from the contribution credit and people's own accounts/metadata, so any manual tweaks like changing 'fix' to 'feat' or whatever have to be one by the actual person making the commit at commit time (not even people with commit access in general). With the new system I have to exclude myself from commit messages if the only thing I'm doing on an issue is committing it, then manually add the contribution credit for the commit - either doing it in the right order or manually editing the commit message to remove myself.

If we get into things like making sure people's email addresses are correct (I managed to end up with three in core commit logs - the no-reply d.o one I was trying to use, my personal email when I forgot to set no-reply on a new machine for a while, and a second no-reply one in a different format that I'm still not sure where it came from), then that is a lot of additional admin work that only the person being credited themselves actually knows about - and they may not have been on that issue for three years.

Issue credit is already the most time consuming part of the technical process of committing an issue (excluding review time, although one line commit typo fixes with 15 people on an issue, not even excluding that). So I'm very resistant to anything that increases that time, even by a little bit.

With #38 do we know whether gitlab's integration works without an email address or not? If not, I'd be fine with just a comma separated list, but it would be shame to change things yet again if it turns out gitlab can handle the format without email addresses.

Possible ways to implement a collective solution:

1. Add another heading to the default issue body template called “Draft commit message”.
2. Adopt the convention that the body of the MR (or at least part of it) should be a draft commit message.
3. Use GitLab commit templates and hopefully get a bunch of the trailers and other goodies automagically per the end of comment #36.

For 1 and 2, core committer copy/pastes from the issue or MR, not the credit UI. For 3, maybe we start merging via GitLab?

For 3, maybe we start merging via GitLab?

We historically haven't been able to do this because it wasn't possible to customise the author on squashed commit messages, and probably other things too in the past, but iirc that's the last one, I think that still might be the case but haven't checked in the past month.

It would be _great_ to be able to use merge trains, but I feel like this issue is one of still several steps before we're able to do that.

Add another heading to the default issue body template called “Draft commit message”.

This feels like it would mean having to maintain both the issue credits themselves and the commit message separately, in different interfaces, and that they would get out of sync all the time. The commit message is also currently generated from the title, but that would also now be maintained in a separate place (or just disconnected entirely).

About #34 and #39, adding a @ in front of the user name would link to the user in the gitlab UI: https://git.drupalcode.org/project/drupal/-/commit/6ba27a8298b3bdf05bab4...

#122312: Yahoo Shopping API feat: something something

By: @nod_

Would transform to a link to my user when reading the commit message, just like in MR comments. I tested the standard format and pictures are broken for some reasons as you can see here, and what gitlab links to is a mailto link, not even the user profile: https://git.drupalcode.org/issue/drupal-3548100/-/commit/4ef708e0473351b...

So either we keep it as bare username or prefix them with @. The actual standard format doesn't look very helpful for us.

Either thing gives us something usable in the gitlab API: https://git.drupalcode.org/api/v4/projects/192716/repository/commits?tra...

In regards to the core issue here, i think a no-reply is fine right? I mean, the username is also there to go to the profiles?

One thing i do need to write of me is the fact I'm kinda agreeing with dww and cmlara on the issue as scope, keeping is full conventional commit style.

feat(#3165412): do stuff
...

I did push on the issue in front for scanability, but i think i was wrong in pushing when its non-conform tooling. :(

Using @username seems good to me - gets us links in gitlab, consistent with the old format that is/was raw d.o usernames etc.

Re #48: thanks for saying so. Glad you agree. This seems like our last real chance to fix this.

Updating the proposed resolution to actually match the standard. 😅

One thing i do need to write of me is the fact I'm kinda agreeing with dww and cmlara on the issue as scope, keeping is full conventional commit style.

feat(#3165412): do stuff
...

I did push on the issue in front for scanability, but i think i was wrong in pushing when its non-conform tooling. :(

I've tried finding what conventional commits says about including issue numbers, but the "conventional" (pun intended..) wisdom is that issue references have no business in the header and belong in the footer as an actual reference (I diasagree, and so do many others in this thread, it seems). The standard says, though:

A scope MUST consist of a noun describing a section of the codebase surrounded by parenthesis, e.g., fix(parser):

See https://www.conventionalcommits.org/en/v1.0.0/#specification, point 4. I think the current proposed resolution answers to this well (it seems to differ from fjgarin's last post, though) [In fact, that's because dww changed it. All good 👍]:

task: [#999999] Convert MediaSource plugin discovery to attributes

This also leaves open the option to use scope what it is meant for, I guess. In short: I wholeheartedly agree with the current proposal, love that we are getting commit messages with an actually readable headline.

I'm going to need people to actually try some tools and report back here with the results before we talk about re-decide anything regarding that first line commit text.

I found unexpected behaviors testing the usernames in #46 so let's not assume what would or wouldn't work with existing tooling. I'd try all the variations (for the first line) of #3439331: [policy] Decide on format of commit message and see what actually comes out.

Main reason was to get the contributors out of the first line, so any variation would achieve this. Now if the rest of contrib moves to this format, let's make sure the tooling they'd be likely to use gives something useful

Is there some sort of list of tooling that people would want to use (or rather: are using)? Obviously GitLab, and I suppose also the drupalorg command line tool by @mglaman (but I suppose that last one is less of interest because it is "under our control"). Any other obvious contenders?

The only tooling I currently use (as a contrib maintainer) that *might* be affected by commit message formats is https://drupal-mrn.dev to generate release notes which also generates links and attribution to those who contributed to a release. Since that is maintained by Matt Glaman, I'm fairly certain he'll accept a fix to support whatever ends up being the solution. The harder thing will be to find those every-day tools that you don't think about as being actual tooling until, you know, it breaks. Things like IDE commit message integrations, cloud-based code hosting tools which turn things into links, git gui and git merge tools, etc. If a 3rd party tool doesn't already support conventional commit formats, it will be easier to request they add support for that than a custom carve-out for a potential non-conforming format.

FWIW durpal-mrn is setup to regex By|Authored-by|Co-authored-by to handle any changes.

https://github.com/mglaman/drupal-mrn/blob/main/api/src/CommitParser.php#L33

Personally I think we should use Authored-by and Co-authored-by and not By. We're copy and pasting the commit anyway.

for the tooling litteraly any tool saying they support conventional commits would work. We talked about using well formatted commits to generate changelogs and such. I would expect some tests with anything in here https://www.conventionalcommits.org/en/about/ and maybe more specifically tools that claim to help generate changelogs like this one: https://github.com/marcocesarato/php-conventional-changelog

might not be used in core but could be used in contrib.

Re #54: the thing we came up with clearly does not conform to the spec. The thing I’m proposing here is a trivial change that clearly does conform to the spec (and IMHO is just as readable / scannable).

Instead of trying to get reports about possible tools in the wild, and whether or not they support the spec, let’s simply follow the spec. if the footer in the contribution records page is going to say:

The message follows conventional commits format.

Then let’s do that. 😅

Meanwhile, here's a "tool" that works with the spec, and is broken by our Drupalism version:

git log --pretty=format:%s 11.2.4..11.2.5 | sort

If we followed the spec, this command would group all commits between two releases by what kind of commit they were. If we put the issue number at the front, this is broken.

Re: footers -- even if GitLab itself supports something useful with @dww (yay!), are we absolutely certain we're going to use GitLab for the rest of Drupal's life? I don't know how anyone could claim that with any certainty. Git, the whole world round, supports email addresses to associate commits with people. It always has, and it always will. That much I feel comfortable asserting. If we're going to be adopting standards for our commit messages (yay!!), and we're going to have useful history moving forward (YAY!!), can we future-proof that history (😂) by using email addresses to help identify people? Then, someday 5-10 years from now, if we decide that GitHub became better, or "GitMonster" (invented) is the new hottest slickness, or whatever, we're not stuck with history that's unhelpful because the new hotness doesn't know anything about GitLab usernames.

I'm okay with the no-reply addresses, if we have to. I still don't fully believe we can't do better than that in many cases, but I don't want to keep delaying this change by climbing up that hill to die on. 😅

But this truly is our last good chance to change this format for a very long time, and I'd love it if we "never" had to change it again. And, I'd love it if our 10 years from now selves aren't upset that we went "all-in" for GitLab specific features. The Git history is forever, and independent of anyone's particular Git tooling at any given moment in time.

To be clear, #61 (if we followed the spec and it worked) would be a trivial and easy way to generate release notes, no fancy tools needed.

Re: #62: My compromise proposal would be:

task: [#999999] Convert MediaSource plugin discovery to attributes

Co-authored-by: @sorlov <xxx@no-reply...>
Co-authored-by: @quietone <yyy@no-reply...>
Co-authored-by: @smustgrave <zzz@no-reply...>
...

Then we get @ slickness from GitLab, but still have something to fall back on if that doesn't work at some point in the future.

@dww this issue was opened because trying to get the right email address for people was turning into a huge amount of work. See the postponed related issues.

I have two no-reply addresses associated with my d.o account as well as my personal one.

I don't think @username is a gitlabism, it's a common approach across social media and various ticketing systems at this point.

I have seen all those issues. I understand the difficulties. Hence compromise #64. (Edit: which @fjgarlin already said was easy in #49).

However, @ is indeed a wide standard. it’s already a step up from our existing “bylines”. So I’m willing to concede #62 and #64. That’s why I didn’t even put them in the summary.

What about #60, #61 and #63? I think that makes the current summary RTBC and we could move forward, without delay.

Added this to proposed resolution:
- Comply with the Conventional commits spec by moving the issue ID to the start of the description portion of the first line. The commit type must be the first word or we violate the spec and can break tools (eg #61) that would work.

Then we get @ slickness from GitLab, but still have something to fall back on if that doesn't work at some point in the future.

Related to this is also how other platforms will render the data. Considering that core is mirrored to GitHub their processing is relevant and should be considered:

Co-authored-by: @alexpott -- No association to user, however you can click the username from the logs
Co-authored-by: @alexpott : Commit associated to the user account.
Co-authored-by: Alex Pott : Commit associated to the user account.

I would suggest that if the intention of commits is to recognize/track those who authored commits then the Core team should encourage allowing GitHub account linking to associate the commit to the users which requires including email addresses.

It is my understanding that #3540555: Authored-by should use email address from commits is currently postponed on a decision here rather than technical limitations.

Related to tooling:
I'll repeat my note above that Co-authored-by has a defacto standard of including an email address, I have seen regexes in tooling that expect/require the Name <email> format, it should be presumed that failing to include email addresses will break some tooling, I have not audited the list of tooling provided above.

nice example in #61, thanks.

To avoid going in circles I'd like to point out that Co-authored-by is not a conventional commit spec/requirement. It's a practice started by github/gitlab to compensate the lack of attribution tools in their system (we tried to help them get better tools, it didn't work out). On our end we have very powerful attribution tooling so the technicalities of how Co-authored-by works are not a concern for us, since this is not how we give attribution, or even show how someone contributes to the community, that happens on the d.o user page, not the gitlab interface. To me the commit message is to help when I do a git blame, not much more.

If there are scripts that expect Co-authored-by to have an email, then we don't use that and use "By" as we've been using for 2 decades.

We used to have

Issue #123 by nod_, dww, cmlara: something something

, and very quickly we could have:

feat: #123 something something

By: @nod_
By: @dww
By: @cmlara

Same exact user information just presented differently. Can we get that resolved and move on?

@nod_, thanks.

Shouldn't this be a task as it is to simply the message for technical reasons?

The proposed resolution here is changing the format agreed to in the policy issue, #3439331: [policy] Decide on format of commit message. Specifically, it is putting the scope first which was an option rejected in the other issue. It concerns me that that recent decision is being overridden in a non policy issue.

Edit: correct issue number

@quietone: for most of that policy issue, the proposals complied with the Conventional commits spec. Late in the game, @bbrala proposed a non-compliant version. I should have made a bigger deal at the time, but I was so excited about progress that I caved in for compromise. But since we’re not implementing the original decision, and changing this “for technical reasons”, I believe it’s worth fixing this mistake. @bbrala agrees in #48. The only “benefit” of the Drupalism is supposedly better scanning by the human eye. But it definitely isnot compliant with the spec, and breaks (at least some) tools that support the spec.

If we need yet another policy issue, so be it. However, We’ve got regular participation from many core committers in here. I assert the intention of the previous policy decision was “adopt Conventional commits and move attributions to footer / trailer lines”. This issue is trying to implement that decision.

Either way, I’d love to keep this effort moving forward ASAP. So if we need to postpone this on another policy issue, can we do that extremely quickly?

Thanks,
-Derek

also where did the brackets come from around the nid? that's something you'd use for jira-style ticket names since there are no defined delimiter, which is not our case.

Removing the brackets, not using co-authored-by because we have a proper credit system in place for that kind of informations and not to confuse tools that might rely on an email being present, we're left with:

feat: #123 something something

By: @nod_
By: @dww
By: @cmlara

We're all happy with that?

In hindsight I was too brief in my comment in #72. Yes, I am concerned that a policy change in being made here in a non-policy decision. That isn't usually a good practice. However, the conversations have naturally lead us here and it makes sense to continue on here until we reach consensus. At the same time we should acknowledge and make it obvious that this is a overriding a recent policy decision. That would be respectful, help with transparency and be good practice to my way of thinking.

nod_ asked me about #72 in Slack. It was then I realized that commenting about the change in this issue summary and in a comment over there would cover my point. And nod_ kindly did that before I did. Thanks @nod_!

Re #76: +1

FWIW, there was already discussion about the "By" vs "Co-authored-by" in comments #7 to #37 and "Co-authored-by" was selected. I personally prefer "By", so +1, but I think we are getting in circles here.

#76 looks good to me.

Correct, and the discussion did not take into account that the goal of Co-authored-by is to either compensate for a lack of proper crediting tools or when commits logs are the whole crediting tool, and neither applies to us.

I also think #76 looks good!

I don't want to block this, so I'm cool with #76. My concern was just Drupal doing something not aligned with de-facto standard by the major repo providers, so that when we're fully on GitLab we're not having this conversation again. Such as GitLab MR's automatically adding the co-authored-by and such. But we can run into the concern in the future if it even happens. Because right now this discussion is for maintainers who are forced to copy and paste a commit message.

Although maybe painfully again at that time matt i agree. If we at some point just let loose By it could mean fully generated commit messages by gitlab. Which would be exactly what would help committers to remove all friction. But for now, this looks good.l, and glad we reopened this discussion. :)

Perfect is the enemy of good kinda applies here hehe.

RE #84, isn't that something that is actually configurable on GitLab? :-)

Let's go with that then. We're reformating the informations we already have.

And we can discuss the trailer format once we use the gitlab ui to do the commits.

@bram #84

Yes but, autbored-by and co-authored by and reviewed-by. Which will take a new round of discussion probably ;)

As a contrib maintainer, I’d have appreciated some heads-up before this is changed again and I just find out when merging an MR the next time. Especially since I’ve now already adapted my custom tooling to work with the old new format and am now supposed to change it again (or spend extra time editing the commit message by hand every single time I merge an MR).
A note about this change on the Contribution Record screen, maybe above the formatted commit message, would have also already helped so I don’t have to hunt around various d.o issue queue to find the correct ticket for the change.

Is the format (at least of the first line) now considered stable or should I wait a bit before adopting the new format?
And is there a way of following such changes affecting all issues and MRs without following all Drupal Core issues, maybe a Slack channel?

Yay, very happy we're all in agreement on actually complying with the conventional commits spec.

Also happy we're currently just using By if we're not going to be more precise about the roles each participant had. And will be happy to revisit this if GitLab can do a better job creating these footers automagically in the future.

I'm still not "happy" we're relying on GitLab @ magic instead of emails. In particular, GitLab seems confused by the @ if the username contains a space:

https://git.drupalcode.org/project/group_notify/-/commit/c8d077eb463bc18...

Not sure if that's just me being stupid, but I believe this is (another) problem with trying to rely on the GitLab slickness. Maybe there are no such users, and I screwed up trying to attribute that commit to 'project update bot'. But it sure looks like we've got folks like "amber himes matz", "gábor hojtsy" and "wim leers" as core (subsystem) maintainers. Haven't tried to credit any of them, but I think @amber himes matz will cause GitLab to try to link to just @amber.

Maybe there's magic under the hood, their GitLab usernames don't match their d.o usernames, the contribution record pulls in their real GitLab usernames, and it all just works. But I'd love to know for sure before we call this "fixed".

Thanks!
-Derek

Whoops, totally didn't mean to assign this. 😂

Meanwhile, pedantic nit about #71:

It's a practice started by github/gitlab to compensate the lack of attribution tools in their system

This is not true. As I understand it, these footers (like Git itself) were developed by Linus and the Linux kernel folks. They've been using very detailed footers to track who wrote, reviewed, and signed-off on basically every change to the Linux kernel for decades. As but one recent example:

commit 506aa235f6e0baa00bf792df82a5e9f618b7a5d8
Author: Christoph Hellwig <hch@lst.de>
Date:   Tue Oct 7 11:06:28 2025 +0200

    block: move bio_iov_iter_get_bdev_pages to block/fops.c

    Keep bio_iov_iter_get_bdev_pages local with the callers, as blindly
    looking at the bdev logical block size is often not the best idea
    unless on a block device.

    Signed-off-by: Christoph Hellwig <hch@lst.de>
    Reviewed-by: Martin K. Petersen <martin.petersen@oracle.com>
    Reviewed-by: Johannes Thumshirn <johannes.thumshirn@wdc.com>
    Reviewed-by: Keith Busch <kbusch@kernel.org>
    Reviewed-by: Qu Wenruo <wqu@suse.com>
    Signed-off-by: Jens Axboe <axboe@kernel.dk>

The very earliest commits in the canonical Linux repo include Signed-off-by: since 2005. Reviewed-by: first appears in 2007, and Co-authored-by: (as a stand-alone footer) in 2013. All of this pre-dates conventional commits, and at least Reviewed-by: predates GitHub (which launched publicly in April 2008). 🤓

This reinforces a point I tried to make earlier. Our Git history will outlive any particular Git hosting provider. I'd really rather we weren't relying on things that only GitLab understands.

Did some digging. Looks like GitLab usernames have no spaces, after all:

https://git.drupalcode.org/amberhimesmatz

So probably the contribution record is smart enough to pull in the GitLab user, not the d.o user, and it will all Just Work(tm) if folks actually copy/paste the message. 😂

I still think this isn't great for all the reasons I've already said, but at least it's not going to be actively broken for some subset of our users with spaces in their names. I think. 😅

From #maintainers Slack:

@mglaman: FYI drupal-mrn is "broken" by the new commit format which added @. I missed that part of the change https://github.com/mglaman/drupal-mrn/issues/444
@dww: Also note, technically these are GitLab usernames, not d.o usernames. 😢 eg in cases where d.o user has a space in their name, on GitLab it’s smooshed together. Not sure about other possible differences between the two sets of usernames. But beware.

This raises a somewhat serious problem with this GitLab-centric approach. All previous release note generating tools that tried to do something with users mentioned in By would link to their d.o profile.

1. Are we now expecting release notes to link to GitLab profiles?
2. Can tools like mrn assume that https://git.drupalcode.org/$GitLabUsername will always work?
3. Is there a way to do an API request with an array of GitLab usernames and get back results that include the Contact field ?

Eg https://git.drupalcode.org/dww points to https://www.drupal.org/u/dww but I’m in the simple case where the usernames match exactly. For folks where they don’t, mentions in release notes will be broken by default unless the tools are ported to understand the distinction, and either only link to the GitLab profile, or jump through some hoops to get from there back to the right d.o profile.

Can tools like mrn assume that https://git.drupalcode.org/$GitLabUsername will always work?

Mostly, GitLab usernames can be changed. GitLab like Drupal does keep redirects when users change names. If someone takes the previous username, that overrides the redirect.

For core's release notes, I was thinking of just taking the first line that has the issue info, without the attribution information. Otherwise, it gets overwhelmingly long and outweighs the human-readable release notes at the top. (We already completely omit the "all changes" section from alpha1, for example.) So it might not even apply to core.

I do agree that the mismatch between GitLab and d.o usernames is a pain, but this issue is just surfacing that, not the source of it.

Also, usernames not being 1:1 with d.o user profile URLs is a longstanding thing for many years not added here?

I hear the concerns, so what should we do? name + email is a no-go per previous discussions.

What would be useful: d.o usernames without @, actual d.o URL to the user, a link to the credit record?

I suggested the @ to keep some level of gitlab integration when not using the name + email pattern.

If it gets more in the way than a "simple" By: d.o_username let's just go with that and not have any special integration with gitlab on the commit message viewing (I'm sure we could find a way to make a gitlab plugin to do it if that's really important)

I think #106 is good.

Late to the party but do we have to use @username? I just 4 emails for 1 Drupal issue

Email that the MR was closed
Email that the ticket was marked fixed
Email about the contribution reminder
Now I’m getting an email from GitHub to a whole other email address with a very unhelpful notification

I don't get those emails, so pretty sure you can configure your notifications :-)
Not sure how GitHub comes into play here.

An unforseen side effect of using @xxx syntax in the commit log is that the mirror on github also parse the usernames and link/notify users. The gitlab and github users do not match so we've been sending notifications to random people on github for a few days. For example, gitlab @catch here is not github @catch.

We can't @ people since we publish on different systems. The concern about different git hosting was raised earlier here, but not as the immediate issue it is today and I missed it.

Thanks to this things are really clear about what we can do: no @, no email, same username as on d.o. We're going with the same information we always had in commits, with a different format.

This is now deployed and there is nothing more to discuss in the scope for this issue. For all the name/email, co-authored-by discussion we already have open issues.

This issue was meant to unblock/sidestep hard problems around the commit body so we can move core to the new format sooner rather than later. Core has now switched to the new format, this issue is fixed.

For all the name/email, co-authored-by discussion we already have open issues

My understanding is those issues were dependent upon this issue and core keeping them in the message format. By closing this issue we essentially will close them as well (unless we open a new policy discussion to change the commit message in core yet again).

This issue was meant to unblock/sidestep hard problems around the commit body so we can move core to the new format sooner rather than later.

I do wonder if this was quicker (both in real time and developer time) than the D.O. Infrastructure team just implementing the changes necessary to have adhered to the original format. Might be worth a survey of time spent on the issue and correlate that to the amount of time Infra would estimated implementation would have cost.

At least on a positive, even though it was not an original intention of this issue, aligned the header portion of the commit to conventional commits so that more tooling will work with the git logs in the future.

We're compliant with the spec, not the practice of attribution in git trailers.

We can open an issue to adopt the attribution practice and go over the email topic, gitlab quality of life features around this more in depth. It'll be an opportunity to list the various attribution options, see how far we're willing to go, what should be the project maintainers responsibility vs. DA automation. and we definitely need to know what it does when our commit messagers are published on github.

Pulling in from side discussion from Slack for issue history:

There was some loss of recognition that this issues was originally opened to focus on the Git trailers and had become sidetracked (hence messages like #115 where it was believed other issues existed to handle the git trailers discussion).

I would suggest its fair to say the Git trailers did not get a proper evaluation in this issue due to accidental guiding of the issue back to conventional commits.