Joshuami

Josh Mitchell is a technology leader, architect of enterprise solutions, and builder of high performing teams.

This work is licensed under a Creative Commons Attribution 4.0 International License.

A guide to issue credits and the Drupal.org marketplace

11 Jan 2016

Republished from Drupal.org

There’s been a lot of positive feedback and a few questions about the recent changes to the marketplace. I want to take a minute and talk about how the marketplace made it to where it is now and mention some plans for the future of the marketplace on Drupal.org.

TL;DR

This is a long post. You may not way to read the whole thing, so here is a condensed version.

We want to highlight individuals and organizations that are actively contributing to Drupal. You can now attribute your work in the Drupal.org issue queues to your employer or a customer. Maintainers can award issues credits to people who help resolve issues with code, comments, design, and more. These credits can roll up to service providers listed in the Drupal Marketplace. (And eventually we want to show customers with credits as well.)

Want to know all the details? Read on.

A little history

Back at DrupalCon Austin (2014), Dries presented a sketch of an idea for highlighting organizational contributions to Drupal to myself and several business owners in the Drupal community. Later that week, those initial ideas turned into A method for giving credit to organizations that contribute code to Open Source.

The idea was to use commit messages to highlight organizational contribution. The first draft looked something like this:

$ git commit -am "Issue #n by INDIVIDUAL@AGENCY*CUSTOMER: message."

It was simple and intended to be parsable from our Git logs. However, contribution is about more than just code—and while code contributions are a good place to start, we also needed to ensure that tools for providing attribution and credit would be extensible to non-code contributions as well.

That initial conversation turned into an issue that spawned lots of child issues and ideas for how best to collect data that allowed a user on Drupal.org to attribute their work to an organization.

The resulting conversations didn’t have a simple solution, but the participation in these issues was lively and full of great ideas. Determining the format for commit credit is still an active issue.

A commit credit format alone was not going to get the information onto Drupal.org. Eventually, we settled on a couple of different solutions for tracking organization involvement and pulled all of this together into the current state of the Drupal.org Marketplace.

Organizations that support modules, themes, and distributions

First, we added a feature to projects on Drupal.org (modules, themes, distributions) that allowed maintainers to reference organizations that were supporting a module—either by providing time to their developers to give back or by directly funding development.

Supporting organizations field

Commit credit user interface

The next part of the work was giving maintainers a better way to create their commit message related to a particular issue. A lot of the complexity of deciding who should get credit for work on Drupal.org was simplified into a UI that showed how many people had participated in an issue, how much each person had participated, and whether that person had uploaded files related to the issue. The UI also generated the Git command that would properly tie the resulting code changes to the issue and people involved. The result for a relatively large issue thread looks like the image below:

Commit credit UI

Attribution

While that effort made it a lot easier to create commit credits, it didn’t solve the problem of attributing issues that didn’t result in code change, nor did it allow people to give credit to the organizations that made it possible for them to work on that issue—by giving them time or by paying for the work directly as a customer.

To do that we had to figure out a way to add organization attribution to the work being done on an issue.

Issues and comments are the primary tools for tracking what needs to be built out in Drupal code. This is where we determine the features, report the bugs, plan out the work, and more. Tracking intent at the point of this interaction was the best way for us to cover the widest range of contribution to Drupal core, modules, themes and distributions.

The resulting UI for attributing a comment to an organization is simple and straightforward.

Attribution UI

While the instructions for attributing a contribution are documented, there’s still some confusion about when to attribute a comment to an organization versus a customer.

Attributions for organizations

These attributions are to allow a person to attribute their participation in a specific issue to a company that allotted time for them to work on the issue. This is typically an employer that pays that person's salary or wage. This organization must be directly tied to the contributor's user profile on Drupal.org as a current or past employer and the organization must have an organization profile on Drupal.org. (Create an organization profile).

When you use this feature, you are highlighting an organization that is contributing code—or other improvements through the issue queues—to the community.

Attributions for customers

When you attribute a customer, you are essentially saying that the work was requested by that customer but you are not employed by them. Typically this means one of three possibilities:

You can select any organization as a customer that has an organization profile on Drupal.org.

When you use the customer attribution, you’re highlighting a different way of contributing to the Drupal ecosystem and often showing relationships between organizations to solve a problem.

Marking a comment with "I'm a volunteer"

Making it possible to attribute organizations who have supported contribution also helps us to gather data on purely altruistic contributions. We went round and round on this attribution feature, but in the end, we decided to add “I’m a volunteer” as an explicit attribution option in the attribution UI. It’s deliberately not the default. This is because we want to collect the explicit intent of the users making attributions. While we are now collecting this data, we haven’t yet figured out a great way to show this intent on a contributor's profile.

Possible intent on a comment could include:

The intent of volunteerism is complex, which is why it is hard to add up into neat little data to show on a profile.

Regardless whether they mark "I'm a volunteer" or not, contributors can still be awarded issue credit by a maintainer for their work on an issue.

Attribution versus issue credit versus commit credit, what's the difference?

Attribution is the first step of the process to award an issue credit. The contributor attributes their work to one or more organizations and/or as a volunteer. The next step doesn't come until the maintainer of the project (Drupal core, module, theme, distribution) gets involved in the process.

Issue credits

Project maintainers may grant issue credits for issues opened against their projects. At any time during the life of the issue, a maintainer can update the credit UI to credit any of the users who have participated in the issue. Any organizations or customers attributed by those users will be credited as well. When the issue is closed fixed, those assigned credits will appear on the appropriate user and organization profiles.

Issue credits are more comprehensive than just code. They can include reviews, designs, prototypes, or just really helpful comments. The maintainer choses what they want to credit even if the issue does not have code associated with it in the form of a patch. This is a great way to help highlight contributions to policy and work to keep Drupal.org running well.

Commit credits

Maintainers can grant commit credits. A commit credit gets added to the Git commit message that accompanies a commit by a maintainer of a project on Drupal.org (Drupal Core, modules, themes, distributions, etc.). Sites like drupalcores.com track this information in the public changelog and use it to highlight contribution numbers based on the number of times a user is mentioned in a commit message.

Commit credits currently can’t be easily tied to organizations, the parsing would be cumbersome and require a lot of precision when maintainers entered the information into Git, which is a big reason why we needed a UI on Drupal.org to help make all the connections and store that information into a database for easy retrieval.

Showing contributions on Drupal.org

Right now, there are three ways that contributions show up on Drupal.org: the user profile, the organization profile, and the marketplace. (We have some ideas to expand this that I will detail below.)

User profiles

Do you log in to Drupal.org? Great! You have a profile.

On every user profile, we show the total number of issues that a contributor has helped fix in the past 90 days.

You can drill into this information and see the specifics. This is a good way to see a facet of how a person is contributing to Drupal. There are other examples on a user's profile that show other ways they are involved.

Organization profiles

Any confirmed user can create an organization page on Drupal.org. Organization profiles are currently related to a single user, but we have plans to roll out additional permissions to relate multiple users to an organization.

On the organization profile, we show the number of issues that an organization has contributed to fixing in the last 90 days.

Organization profiles also show a list of modules that have been supported by that organization, whether that organization is a Drupal Association member or Supporting Partner, and additional self-reported information about their involvement in the Drupal community.

We are currently working to automate more methods for collecting data about how organizations are contributing to the community through DrupalCon and Drupal Camp sponsorships as well as hosting user groups to help support meetups, and giving to Global Training Day events. The number of case studies associated with an organization is another indicator of how much they use Drupal and how they are helping get others to use Drupal by sharing their success stories.

Marketplace

We recently rolled out some changes to how the Drupal.org Marketplace is ordered in order to better highlight contributing organizations.

Currently, the marketplace is sorted by number of issue credits awarded to an organization in the last 90 days, then whether the organization is a supporter, then by alphabetical order.

Every organization on the marketplace shows counts of its users on Drupal.org, projects (modules, themes, distributions, etc.) supported, issue credits in the last 90 days, and case studies. We also highlight organizations that are funding the ongoing support and development of Drupal.org by being in our supporting partner programs.

Questions we have heard

While most people have been excited about the changes to the Marketplace, there have been several questions.

Why is it only Drupal Service providers?

The marketplace was originally created to highlight Drupal service providers that are active in the Drupal community.

A "Contributing Organizations" list is the next step to expand the types of organizations we highlight. There are community members that are already working to highlight customers using Drupal that contribute back, community volunteers, and volunteers that are working for organizations that rely on volunteerism (many camps fall into this category).

These are great ideas. Contributing to those issues is a great way to help us figure out the best way forward.

What about "x" contribution type?

Yes, there are many ways that organizations contribute. We are definitely hoping to add in contributions that we can objectively verify. There are so many great things that organizations can do to support Drupal, both the local and worldwide community, and Drupal.org, including:

There are many other phenomenal ways organizations give back. If you know of one that has objective data that can be added to the algorithm we use to highlight organizations, let us know by creating an issue in theDrupal.org Customizations queue.

Why is it so hard to create an organization profile?

We definitely want to improve this process. There are over 650 organization profiles on Drupal.org, so we know that people have figured it out, but it could be much more intuitive.

We have also had a several requests to add permissions to organization profiles so that multiple people can be editors of those profiles and help administer who is allowed to be associated with the organization. Our current method of tying users to organization by using an exact text match is a bit clunky. (If you want your organization to list you as an employee, you must exactly enter the title of the organization as it appears on the organization profile and list that organization as "current".)

What about more tools for individual contributions?

We have so many thoughts on how to improve the way we highlight individuals on their profile. We already show issue credits, documentation edits, commits, and lots of self-reported information. There is a lot of objective data to pull from including DrupalCon attendance, whether they have been a speaker at a DrupalCon, translation strings submitted to localize.drupal.org, Drupal Association membership, modules maintained, and many more.

Engagement with the community involves a lot of factors and we want to highlight as many as possible while still making the user profile useful and relatively succinct.

Help us make Drupal.org better

In addition to the questions that have come up above, we want your feedback to keep improving the user experience on Drupal.org and make it easier to hightlight the companies that are doing so much to make Drupal the leading platform for the web and the individuals that provide their expertise and commitment to the community. Drop your ideas into the Drupal.org Customizations queue.