search

archesproject / arches

Arches is a web platform for creating, managing, & visualizing geospatial data. Arches was inspired by the needs of the Cultural Heritage community, particularly the widespread need of organizations to build & manage cultural heritage inventories
GNU Affero General Public License v3.0
219 stars 144 forks source link

Capture Non-Code Contributions In Commit Comments #3323

Open jvasile opened 6 years ago

jvasile commented 6 years ago

Arches is losing some important metadata about commits. In addition to the committer, we also want to credit designers, architects, and other people who have contributed to a patch but in ways that aren't visible in GitHub's information stream. This data should be structured, etc.

The types of information captured by this metadata would include "Designed by foo" or "Farallon working for GCI", etc. This will allow the community to better understand where development energy comes from and how it affects the project.

Definition of Done

A documented way to specify the above using structured data dropped into commit comments.

jvasile commented 6 years ago

@kfogel This should interest you.

kfogel commented 6 years ago

For some prior art, see the "Crediting" section in the Subversion project's development guidelines. Obviously the exact conventions will have to be adjusted for the Arches Project, but the pattern used there is pretty flexible. Basically, the commit message contains expressions of the form:

  Sponsored by: so-and-so
  Found by: so-and-so
  Tested by: so-and-so
  Designed by: so-and-so

Etc. When the convention is consistent, then it can later be parsed in order to generate informative quantitative reports on who is doing what in the project.

Since the Arches Project has been running for a long time and thus has many commits already made (whose commit messages cannot be changed now), consider adding the metadata retroactively with Git notes:

It might even make sense to add this kind of metadata exclusively via Git notes, in other words for future commits too. I haven't thought deeply about the advantages/disadvantages of that, but the obvious advantage is consistency: a particular kind of metadata is always preserved in the same way. I guess the obvious disadvantage would be that when the committer knows the metadata at commit time, it's convenient to include it in the commit message directly rather than having to run an additional command.

Happy to help think this through further, of course. This comment is just to make the high-level suggestion more specific.