[meta] Provide credit to organizations / customers who contribute to Drupal issues

See also #968994: Multiple Values for listings of current companies and organizations. The issue comment form is already complex, so we'd want the select box to only show companies someone is affiliated with. I think the dereference_list module we use for issue components may help the customish code down.

The Git log message parsing is Git-specific, I think the change will land somewhere in http://cgit.drupalcode.org/versioncontrol_git/tree/includes/plugins/repo...

I'm not sure if this is just an implementation detail of the mockups, but I would strongly, strongly encourage us to not overload the commit message with the data. I think we could also make a field to supply it as git notes.

Edit: Meant to say, I like the look of the mockup in #8 other than that point. :) Nice to attach it directly to a patch.

So... Consider this use case:

On a particular issue, let's say person A adds a patch and wants to credit her company Z. Then person B adds a patch and wants to credit his company Y. And person C goes back to person A's patch, modifies it, makes a new patch, and wants to credit his company X.

As a committer, I decide that person B's patch was not useful (or maybe it was uploaded to the wrong issue or whatever), and I want to just credit person A/C for the commit, so I should also just credit company Z and X, but not Y. Will there be an easy way for me to collect that information? There needs to be, or this becomes a huge burden (especially on a large issue) for the committer to gather the company information together.

Does that mean that a particular contributor could only supply one company for credit?

When the details are figured out, I will help out on the design part

I am wondering, design-wise a side. Does it make sense to "comment" on behalf of an organisation? I can imagine that organisations would feel quite uneasy about such a feature.

The best way to promote contributions from an organisation stand point, would be to bring this "commit" information to the organisation profile. But also improving the way we list organisations by contribution.

I agree with Bojhan that "commented on behalf of" is problematic.

Maybe we just need to change the wording to "Work supported by" or something like that? So it would say (maybe):

-- field:
Contribution support
() individual () Employer/Customer

(optional) Specify whether this contribution was done on your own volunteered time, or was supported by one of [link]your current organizations and/or customers[endlink].

-- comment header:
(user name) contribution supported by (org1) (org2) ... (date)

Thoughts?

This will be awesome to be able to credit organizations and groups, and yet maintain the individual's contribution as well. Love it.

I would like to echo @xjm's concerns in #9 - I think we should avoid attaching more metadata about a change to the git commits that represent those changes. Even putting credit into the commit messages seems unusual to me like @webchick said in #15

we should probably remove the usernames from the commit messages themselves (which would eliminate a Drupalism as well).

It seems to me that coming up with a format to store credit in git is inventing another drupalism.

It may be true that other projects attach some kind of metadata to their git data, but those projects don't already have a great metadata repository that could handily manage all of that data (drupal.org in this case), so why not use drupal to store that data?

We already provide a pointer to all the metadata that is associated with a commit, the issue #. What if all of the credit related information was additional fields on an issue? It seems that project maintainers could update credit on an issue when they close an issue (or at any time), additionally if we decide there needs to be new *types* of credit granted (like reviewer credit or sponsorship credit) it'd be much easier to add that to the interface on d.o. These form elements would not be visible to most folks, only maintainers.

It feels like we're trying to use git as some sort of metadata database, and that we're looking at ways to serialize that data into git (https://www.drupal.org/node/2323715), and we'll need to get that data *out* of git to use it on the place where its useful (drupal.org) - so why not store it on d.o. in the first place?

also write it out to Git for external tools to parse

External tools have a new option, what Drupal.org provides via RestWS. Since we'll almost certainly leverage fields for this, it will appear in the API without extra work. Either way, 3rd party tools are either implementing something new to read either our API, or something new to read our special Git data. The special Git data does have a chance to be adopted by other projects, but I expect not without someone motivated working within the Git community.

I thought one of the reasons we didn't allow an interface for re-assigning author in case of a screwed up commit, etc. was because the VCAPI tables were essentially a "cache" of what was in Git and could be rebuilt randomly. I guess sdboyer or marvil07 would know.

Changing Git's --author or commit message changes the commit hash, so that's set in stone as soon as your branch is pushed publicly.

VersionControl re-parsing does change some sequentially-assigned IDs, and is smart enough to update changed IDs in tables that refer to it. For example, the ID that a release node uses to point to the branch or tag is kept updated. We can do that again; or store the reference as a commit hash, which won't change.

The special Git data does have a chance to be adopted by other projects, but I expect not without someone motivated working within the Git community.

I think that would be possible if what we were trying to define had a widely accepted data model. But we haven't agreed as to how to define attribution, and whether and how to segment the nature of peoples contributions. Who to give credit to (individual/freelancer/employee, the sponsor/client, the employer, the client), and how to categorize the nature of their contributions (reviewers, patch writers, patch editors, issue opinionation, sponsorship, testing, administrative requirements gathering, mentoring) can be looked at in many ways, and organized in many ways.

I think that each project would have different enough crediting requirements that Im doubtful that we'd be able to come up with a model that suits other projects without first researching or consulting with them to find what they need. Ultimately we're trying to see who's responsible for helping create the delicious Drupal cake, so I would think that building something that works for other projects would be a bigger thing that we would want to take on.

@webchick Just wondering here - can we not do the "by" part at the end of the commit message. Then we can have the "meaningfull" part readable and just add an ellipses for the rest.

+1 for #31. I was just going to say the same thing.

There is not much mention of reviewer credit here but @Dries linked to here from https://twitter.com/dries/status/502805736020537344. Is this issue to cover introducing reviewer credit (eg. the necessary Dreditor changes, etc) or another issue should be opened?

As discussed on twitter, our current process lacks giving credits to reviewers. However,

• it actually takes more knowledge for being able to tell whether something is a good chance or not than writing it
• doing proper reviews takes a lot of time, sometimes even more than writing it
• the lack of any credits for reviews does not encourage people to review more code. That's in particular problematic as most people would probably consider writing patches being more fun anyway.

RE #35 - When I make commits to Drupal Core for Documentation patches, I normally try to credit:
- person who wrote original issue pointing out the docs problem
- anyone who suggested wording
- anyone who reviewed
- people who actually created patch files

I do not know what the practice of other committers is, but... to me "credit" for a patch is shared and all of these types of people contributed to the patch. I do not use dreditor so I am not relying on it to make my commit messages... and I think there is a separate issue about patch credits anyway and we shouldn't be discussing it here... so I just contributed to the problem. :(

Related:

I think this needs an updated summary, then the Dev Tools team needs to figure out the UI and implementation.

I've done a few explorations. I think it makes most sense to hide this functionality behind a link. I assume most users won't be switching between company and individual all the time. Therefor we can show it behind a additional click. It also gives us more room to explain the choice they are making and possibly link to relevant sources.

The idea below is relatively minimal, but I expect some more discussion around this. The only thing I truly worry about is the inability to add customers here, perhaps we can provide linking or an actual add button. I think this is up to drumm to decide.

@webchick That's true. Though I hope the label triggers the "concept" of individual/company time contribution. Perhaps we should pick a better label? People often don't read help text and the issue metadata part is already pretty filled with help text.

Untagging since Bojhan is providing feedback.

I agree the "Contribution type" label isn't exactly right. Maybe something like:

Attribute contribution to myself [edit]

+1 pm #46 also!

Oh, thats a great idea. Adding to that - I would go with "Bojhan Somers" and not "myself". From what I've seen in the countless usability tests I have done, is labels like "myself" "me" don't really perform well as people don't immediately recognise them.

Frankly this is quite ready for some technical input, I am sure we can figure out the details of the UI from here on.

Updating the issue summary with images from #42. It looks like the issue summary is missing more, such as the resolution to this from #22

I agree with Bojhan that "commented on behalf of" is problematic.

As I said at the time on Dries blog post, "The true value however will come with how we aggregate this data. If we do a good job of that and feature it prominently on d.o it will have a good impact on community engagement."

It's no small task to allow folks to give attribution in the git commit logs, or for that matter to give proper attribution on issue queue pages. However, we need to do more to highlight those organizations and individuals who are contributing. We need this data, so we can know how people are contributing, but it will only be a motivator for companies when aggregations of these contributions get featured in prominent locations on Drupal.org.

I like "Attribute contribution to Joe Bloggs", but we need to get the agency and client in there too.

How about "Attribute contribution to {name} of {agency} for {client} [edit]"
(obviously "of" and "for" would disappear when not required).

This idea is mentioned in @dries Amsterdam keynote https://www.youtube.com/watch?v=4NN5EM4CYVE&feature=youtu.be&t=35m

Legal question: if this end up in git logs, how copyright is affected? i.e. does organizations and customers also get copyright?
By default her in d.o all is GPLv2, so license is not the problem, but it would be great if someone can actually clarify this legal aspect before we decide to implement it.

Responding to #57 above, I am pretty certain that EVERYONE ends up as a copyright owner. This article does a great job explaining how copyright and licenses intersect:

http://www.majordojo.com/2010/07/license-vs-copyright.php

If in my spare time, I help build a site for a friend's organization, are they my customer? I suppose they are. The word gets a bit awkward, but I can't think of an improvement like the "company → organization" change.

If your friend's organization you are working for pro bono expects you to credit them, then they are your customer. In this case though I think I would personally not credit them, since they are not really sponsoring the work in any way... up to each individual though, right? I think "customer" works fine.

Given the issue title here, which is not specific about what "contribute to Drupal" means, I'm wondering if we would also want to give credit to people who do contribute their time by making Drupal.org documentation edits? Could we have a similar field people could fill in on a page revision? Just a thought that occurred to me. May be out of scope for this issue.

Clarifying the title. This is very much focused on issues.

Thanks to #2416177: Use Comment fields instead of custom textarea. this is fitting nicely into nodechange's existing work on comments. Documentation pages will have to do something different, since they want to remove, not accumulate, comments. Maybe a regular field on the node with a bit of customization could cover it.

The recent work on #2323715: [policy, no patch] Determine format for commit credit for individuals/organizations/customers clearly cements the organization/customer split.

Should both be multi-select? Either will of course be easier to make a more-striaghtforward UI if single select. It looks like all the mockups are multi-select, with the possible exception of #5.

Is everyone okay with customers being associated with users, #2323709: Add a "Current customer(s)" field?

This is a nice idea, but I think hardcoding "employer vs. customer" directly into the field structure would be a big mistake. @drumm's comment in #60 is one reason - this does not take into account the variety of ways people actually contribute. Here are some other problems:

1. There is no way to indicate that a contribution was part-volunteer and part-sponsored-by-employer. Not sure about other people, but for me a significant amount of Drupal work I've done over the years falls into that category. I think it's especially common when you're working for a company that doesn't really have a strict boundary between work time and volunteer time :)
2. There is no way to distinguish between (a) work done as a volunteer, and (b) paid work done under an NDA. Again this is pretty common (I've been in situations where 100% of my Drupal work was in one of those two categories). With the current mockups, although there is a way to distinguish between those on the editing screen, the hardcoded "employer/customer" split means it's not clear that would ever make it into the field storage in the database (and the current mockups for the comment view do not show it being distinguished there either). I think it's important that this distinction be stored somehow.
3. It doesn't fully take into account that the same organization can be both a employer and a customer. (It's often the case that a large organization will hire some of its own Drupal developers while also farming out some work to agencies and contractors.) I suppose it's not impossible for that to work with the current proposal - nothing stops the "employer" and "customer" fields from both having the same organization as an option - but overall it seems like it would be an awkward process.... would the organization have to "register" as a customer and employer in order to be listed as an option in both fields, or...?

A better way to do this that solves the above problems while being a lot more flexible for the future would simply be to have a single multivalued "organization" field (or actually, more like a multivalued field collection, with each element containing an "organization" field and a "relationship" field). Examples below.

Standard situation with an agency hired to do work for a client:

I did this work for [Organization 1] as a [employee]
            and for [Organization 2] as a [client]

Mix of employer-sponsored and volunteer work:

I did this work for [Not specified] as a [volunteer]
            and for [Organization 1] as a [employee]

Contract work done under an NDA:

I did this work for [Not specified] as a [client]

etc.

And if you ever need to add a new kind of relationship later on (besides examples like "employee", "volunteer", "client", "contractor", etc) then it's as simple as adding a new option to the select list, rather than redoing the entire field structure and user interface.

Legal question: if this end up in git logs, how copyright is affected? i.e. does organizations and customers also get copyright?
....
Responding to #57 above, I am pretty certain that EVERYONE ends up as a copyright owner. This article does a great job explaining how copyright and licenses intersect:

http://www.majordojo.com/2010/07/license-vs-copyright.php

I read that article but don't see how it answers the question above. (Clearly the copyright on Drupal as a whole is shared between many many people, but the question was about the copyright on particular contributions and whether the organization owns some of that.)

I think it's a good question actually. My understand is that (in the U.S. at least) copyright belongs to the individual by default. An organization would only own or share in the copyright if you signed some contract with them saying that you're granting them the copyright. And I doubt that merely filling out a field in the user interface of Drupal.org that "attributes" your post to an organization would count as giving up copyright...

But I am definitely not a copyright lawyer, and I have even less of an idea how it works outside the U.S. :) So I think this is worth clarifying.

I've been running with the assumption that multiple organizations and customers can be selected. Here is a mockup of a potential UI, that would go above the comment textarea. Depending on how the size works out, we might even be able to nestle it to the right of the HTML tag buttons on desktop sizes.

I don't think this belongs in issue metadata; for commenters, this is set per-comment. Future work on the Credit & Committing UI will let maintainers collapse this into per-issue credit as it is fixed.

My main goal was to lighten up the UI. Modals can be obtrusive. Replacing with a bubble provides enough screen real-estate for a little UI on each element, and keeps you in-context.

The attribution when viewing the comment should match, omitting some words:

drumm at Drupal Association for Acquia, Chapter 3 commented 12 days ago

#2323715-56: [policy, no patch] Determine format for commit credit for individuals/organizations/customers is probably the best recent explanation of the organization/customer split:

Study how the community works, by studying the relationships between customers, agencies, and volunteer contributions and how and where the money is flowing.

At this point, I think we should try it out and see if people do credit their customers. Whatever we end up with will simplify the relationships to fields somehow.

#69 is now implemented at #2340363: Add issue comment attribution.

I never got an answer to #66:

Should both be multi-select? Either will of course be easier to make a more-striaghtforward UI if single select. It looks like all the mockups are multi-select, with the possible exception of #5.

Oh well, I'm running with multi-select for both.

I think at the moment it must be a multi select right? Assuming it can often be multiple.

If you have not taken a look at the comment UI, you should at #2340363: Add issue comment attribution

Should we embed that demo gif in this issue summary? That is a very creative way to get feedback on UI functionality before completely coding the back end.

@David_Rothstein, we have time to work out the specifics of how we write to the commit message, but this issue is focused on collecting organizational attribution for work on an issue. We are storing the intent on the comments in the issue and can store per issue credits at the time of closing an issue. Because each comment is attributed, you could change your settings on a per comment basis to go from doing work on your own as a volunteer to doing work for your company as an employee to doing work for a customer directly or through a company. It is flexible intentionally as many issues remain open for long enough for someone to transition several times.

You make a good point about work done under an NDA. You would not be able to disclose that work, so we would not see a customer accordingly. It would be interesting to hear from @webchick or @Dries. Do we want contributors to have the option to specify that work is being influenced by undisclosed organizations? It seems like that would create unintended tension and it would be better to simply not attribute a customer at all.

As for copyright, organizations getting attribution for enabling the work does not change the fundamentals of how copyright works for an opensource project. All contributors to the project have copyrights to their contributions. It is part of why a project with many contributors is virtually guaranteed to remain open source. This is a clear benefit to all the contributors. In this case the copyright would still be held by the individual rather than the organization that is being credited. (We do not allow organization accounts to contribute code per our terms of service.)

Thanks for the feedback, @joshuami.

My points in #67 were only referring to the comment attribution, not commit messages. Even if you can do different attributions for different comments, writing and uploading a patch just takes one comment but often involves a lot of work that may be split between volunteer and employer time. That's the problem.

That concern (#67.1) was definitely my main one, though it does occur to me that it could be partially addressed just with some wording changes => When you click "Drupal Association" in the example, perhaps the text should be "Attribute this contribution to myself, Drupal Association" rather than just "Attribute this comment to Drupal Association". I'll leave a note about that in the implementation issue.

That would make things better, but it still leaves out so much useful data. If you want to be able to answer questions like "what percentage of Drupal contributions are volunteer vs. paid" or any other similar questions, storing things like in #67 makes that possible but otherwise the data simply isn't there. I'd certainly love to be able to see the answers to those kinds of questions. What do others think?

Documentation to update as parts of this are rolled out: https://www.drupal.org/node/2451283

@drumm, excellent work. On a thread this long, it does not stand out too much.

I currently plan on deploying #2369159: Extend crediting UI to include organizations & customers and working on #2453271: Make "I'm a volunteer" an explicit choice in the credit UI this week.

#2506223: Commits percentage per Author & Author organisation members vs community members Talks more in dept about the statistics and a way of displaying for/to businesses.

It seems credit given in the beleaguered Project Application review queue is not being included on profiles or anywhere else, so i've opened #2810485: Allow more maintainers to grant credit to address that.

Looks like the most important parts of this are done. The remaining child issues are nice to have improvements.