Contributor attribution in Git history

[patrick-motard]

I wanted to open a discussion about how contributor attribution is handled in the Git repository, building on some points raised in #4419.

Background

tmux is developed in OpenBSD's CVS repository, with Git as a mirror. When contributions are accepted, maintainers apply them to CVS, and those commits sync to Git. Because the CVS committer becomes the Git author, external contributors don't appear in the Git history's author field.

The concern

The Author field is a Git feature, not a GitHub feature. This metadata is visible in any Git tooling - git log, GitLab, Gitea, self-hosted instances, etc. So this isn't about adapting to GitHub specifically; it's about the format the project already publishes in.

Visible attribution matters to contributors. Many use their commit history to demonstrate work to employers, collaborators, and the broader community. It's a meaningful motivator for open source engagement. While tmux has a healthy contributor base, accurate Git attribution could lower the barrier for new contributors and recognize the work of existing ones.

Possible solutions

Since the CVS workflow is established and changing it isn't practical, the solution would be in the CVS→Git mirroring process:

1. Parse commit messages during mirroring - Contributor names already appear in commit message text. The mirroring script could extract these and set --author accordingly when creating Git commits.

2. Maintain a contributor mapping file - A simple file mapping contribution descriptions or PR numbers to author name/email. The mirroring process references this when creating Git commits.

3. Add Co-authored-by trailers during mirroring - If setting the primary author isn't feasible, trailers could be appended to Git commit messages during the conversion. This preserves the CVS commit message while adding Git-standard attribution.

None of these require changes to CVS commits or the maintainers' workflow - just a one-time update to how the Git mirror is generated.

Summary

This isn't a criticism of how the project is run - tmux is well-maintained and has been for years. But I think this is a small change that could have a positive impact on contributor engagement. Happy to hear other perspectives or help with implementation if there's interest.

[nicm]

I am OK with any of these so long as you are going to do the work to set them up.

Any time this has come up in the past I have suggested adding a CONTRIBUTORS or CREDITS file like you do in point (2). And if you built one to start with, you would probably find it is fairly easy to maintain, because it would be easy enough for me to fill it in as I go or when I build the CHANGES file, or some (CI?) tooling could be built to generate it from commit messages and work out if anyone was missed. And we would no doubt find that people who really care would include a change to it in the MR, or point out if they were forgotten.

I can also try to use a standard form of text (I usually do "from X in GitHub issue Y", or "from X", or "from X via Y", or from "email at domain dot name") for automated parsing, but it is important that there is a way to manually tweak them because inevitably there will be typos or people will be missed. Also I don't feel there is any point in crediting people who choose to be anonymous - I do try to track down a name or email for contributors but if they choose only to use an alias then I think it is safe to assume they are happy to go without credit (so far nobody has complained).

Using Git features is OK, if Git ever goes out of fashion there will no doubt be ways to deal with it. I don't really want to use GitHub features because then if and when GitHub do a SourceForge and we have to move, we are stuck with a load of GitHub metadata in the commit messages. Although TBH source code history is useful but not that important for a small project.

[patrick-motard]

I can set it up. Thank you for being open to this idea. To make this solution as automated as possible I would like to understand what the current process is for merging pull requests. Is it done locally or do you have automation in place?

[nicm]

There is a file called SYNCING in the repo which explains how it is set up, although it is written as if someone was doing it manually in fact I believe @ThomasAdam has a script and only intervenes manually when there is a conflict.

[ThomasAdam]

I am OK with any of these so long as you are going to do the work to set them up.

I'm not so sure I'm that happy about it.

Right now, the only guarantee we have is authors who have the commit-bit in OpenBSD's CVS repository have a .mailmap entry which git log and other commands will use to give more meaningful attribution.

@patrick-motard to your other points, there's no "mirroring" here in the way I think you're thinking of it. It's just a straight-forward git cvs-import using cvsps.

I absolutely do not want there to be any commit rewriting as part of this synching process as that would introduce a lot of complexity. I know @nicm sticks to a good/predictable set of meta fields for attributing contributors, but other people with commit bits to the CVS repo might not follow the same format. and then we're into other issues.

What we could do (and this is a git feature) is maybe try and standardise on some of the commit trailers in commit messages, such that they can be used by git interpret-trailers, and the underlying git plumbing to make use of this information. But you've always got the historical point of having to deal with a pickaxe regex to pull out the attribution using the wording which @nicm uses at the moment.

What I'm saying is, I don't want to filter commits from OpenBSD into -portable just to make the attribution part of the commit message per se -- all of this has to be done after the fact.

[ThomasAdam]

I can set it up

The better approach is for me to move this synching malarkey to a GitHub actions script and make that a more predictable operation, rather than relying on my FreeBSD box doing this.

It's on my list to look at soon.

[nicm]

I think it would be great if syncing was done through GitHub yes.

Couldn't the changes be done by a script when going sync-branch -> master?

If we're concerned about it screwing up, I'd be happy enough to have an extra step, so instead of it going CVS -> OpenBSD_sync branch -> master it goes CVS -> OpenBSD_sync branch -> OpenBSD_staging branch and then we merge the staging branch into master manually after reviewing the commit messages. This would also make it less disruptive to fix any problems.