Tracking contributions

[plehegar]

We need a convention in commit messages to help track contributions.

e.g.

"Added foobar(). by @darobin"

"-@darobin (Robin withdrawn his contribution)"

[astorije]

@plehegar, are you talking about all git commit messages across all our repositories or just this one? Or something else?

I don't think it's a good idea to add one's username in a commit message. First of all, it's not common, so people will often (if not always) not do it. Maybe because they forget, maybe because they don't want to, no matter the reason, it will be hard to enforce. Additionally, git will not let you commit anything if you haven't set your name and email in your git config (email is what is used to link a commit to a GitHub user, and that's how you pretend to be someone else on GitHub :wink:), so that's a way to track contributions. GitHub then uses that to build all their graphs.

In terms of commit message convention though, I always use imperative tense as recommended by the git doc for consistency and clarity:

It’s also a good idea to use the imperative present tense in these messages. In other words, use commands. Instead of “I added tests for” or “Adding tests for,” use “Add tests for.”

[plehegar]

@astorije I'm talking about all repos that are used for spec editing under the W3C Patent Policy (CGs and WGs). Yes. I realize that committers may forget but if we can wire that into their culture, it'll make the tracking more precise.

[astorije]

I realize that committers may forget but if we can wire that into their culture, it'll make the tracking more precise.

Can't you use the per-commit author information for that?

[darobin]

Nope, unless I misunderstand the docs. You can only replace the (one) committer with the (one) author; you can't say that five people contributed to this work.

[tripu]

It may be that I don't understand well this use case, but I think I agree with @astorije: this would be an awkward rule.

Commits already contain basic metadata (author, date and time, etc). I don't think we'd succeed in trying to give structure to the commit message.

If the problem is having GH users committing bona fide on behalf of others, or identifying a group of people who worked together on a single commit, can't we use the description of PRs to hold that extra information? The same tool that would examine commits to extract those usernames could examine merged PRs instead, for the same purpose.

[darobin]

The description in PRs should work under this scheme as well, but a PR description is AFAIK just what goes into the merge commit — no?

Note that this isn't really structure, it's just mentions. You mention the people who worked with you.

[tripu]

@darobin When merging a PR, GH pre-populates the corresponding commit message with the title of the PR (the short heading). The comment (the longer text; what I wrongly called description above) is lost from the Git history, AFAIK — it exists only in GH's list of merged commits. (Am I wrong here?)

The cleanest solution here, I think, would be to encourage folks to append that info at the end of the comment of their PRs:

This PR adds these features:

• Upgrade flux capacitor to latest version.
• Fix many typos.

Thanks!

[authors @darobin @plehegar] [reviewers @astorije] [requestors @dom @tripu]

Or whatever we need (I'm making up some “fields” here, just to see what this might look like in the future, if it grows/evolve).

I suspect that adding that info to commit messages or PR titles instead is going to make it @very @annoying @to @browse @commits @and @read @PRs.

[darobin]

Ah, I was unaware of the difference between the short and long text. Thanks!

I think that this works. We can get the data anyway. The only goal is to gain more IPR tracking so I would make it really as simple as possible, just mentions, or worst-case just Contributors: @tripu @plehegar. If it's not super-simple it won't work.

@wcarr Do you think it would work if this were only on pull requests?

[wayneca]

What this is for -- In Community Groups, required patent licensing obligations are for one's own Contributions. In Working Groups, it is for the whole spec, regardless of who contributed it (Community Groups have that only as an option, not required). In Community Groups, there also often is a much less clear set of deliverables and specs can suddenly appear (depending on the charter). People are thinking about types of Community Groups where there could be a large number of specs, where new specs often appeared. With all that, for Community Groups, it would be useful for a company to be able to determine what specs their representatives were making Contributions to (the only documents that this applies to). So it doesn't matter who reviewed it. It's who contributed to the technical content of the change in the spec. All Community Groups have a "contrib" mailing list. If all the GitHub events (PR, commits, whatever else) were sent to that and there was a fixed format for listing Contributors in PRs and commits, a tool could crawl that and send a report to AC reps for what specs their representatives were contributing to. With a very large Community Group, with a very large number of specs and a very large number of people, it would be difficult to be able to tell what specs a company is being obligated for otherwise. So, this is only needed for specs in Community Groups. The comment for the Commit is the essential place, though pull requests would help for them to create that. [Contributors: @tripu @plehegar] would work. If someone didn't know who the contributors were or forgot, it would still be better to know at least for the places Committers did do it. (who really contributed what would often be in discussions of an issue, but we need something that could easily be automated that covers most cases).

[wayneca]

Just to be clear on this -- this wouldn't be the exclusive way to determine who made contributions. That's, like always, if anyone needed to find out it would be in the archived mail list, in meeting minutes, GitHub Issues, PRs, Commits. If someone forgets to do this, it doesn't change actually Contributions that are documented some other way. This is to allow for an automated check on which W3C Members (and others) are contributing to which Specs in Community Groups,

[tripu]

This requirement now has its own dedicated tool.