Ensuring Proper Attribution for Contributions to WordPress on GitHub

Edit Feb. 1, 2022 @ 00:45 UTC: Added note clarifying that this is currently a suggested change for the GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ repository, but should be considered for all GitHubGitHub GitHub is a website that offers online implementation of git repositories that can can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ repositories going forwards to ensure all contributors receive credit for their work. – @desrosj

Edit Feb 3, 2022 @ 03:50 UTC: This proposal has been withdrawn and will be reissued taking feedback in the comments section into account. Please feel free to leave any additional thoughts you may have in the comment section. – @desrosj


One of the greatest things about open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. is that contributions come in many shapes and sizes. Anyone can contribute regardless of skill set, experience, time zone, or background. There are countless ways for someone to get involved with open source projects.

WordPress is no different. Contributors submitting code modifications are only a small subset of the larger community. Recognizing all types of contributions is essential to establishing a healthy contributor base, and the responsibility falls on the project’s maintainers. Contributors that feel recognized and valued are more likely to continue contributing.

There is an established and documented policy on the TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress./SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase. side of the project to ensure that everyone contributing to a changeset receives credit (or “props”). This method has been in place for over ten years now and makes generating the list of props for each release scriptable and straightforward. The process is a bit unique to the project but frequently receives positive feedback from others in open source.

Since being merged into WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. in version 5.0, there has not been an equivalent process for the contributions on GitHub. The process is manual, does not account for non-code contributions, and often results in contributors not receiving credit for their work.

This post summarizes the current processes in place for Trac/SVN and GitHub to understand the shortcomings and propose a small change to ensure more people receive proper attribution for their contributions made on GitHub.

Current Processes

Trac/SVN

When a commit is made to the WordPress source code in SVN, the person committing the code is responsible for collecting a list of WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ users that contributed to moving a ticketticket Created for both bug reports and feature development on the bug tracker. towards a resolution.

Props should be given to all those who contributed to the final commit, whether through patches, refreshed patches, code suggested otherwise, design, writing, user testing, or other significant investments of time and effort.

WordPress Core Handbook – Commit Message Guidelines

The guidelines also encourage committers to “err on the side of giving props liberally. Props provide major encouragement for contributors.” Commits themselves are considered a contribution, even if the committercommitter A developer with commit access. WordPress has five lead developers and four permanent core developers with commit access. Additionally, the project usually has a few guest or component committers - a developer receiving commit access, generally for a single release cycle (sometimes renewed) and/or for a specific component. does not include their name in the props list (see the section on self props).

When a release is near, all of the commits in the current release cycle go to a text file via git log, and a private script parses out every “Props x, y, z.” line to tally up the number of props for each contributor. After this, the list is groomed for duplicates and incorrect usernames/typos.

Gutenberg

There are currently no documented best practices for giving props on GitHub. There are two primary ways that props are currently given: when merge commits occur and when Co-authored-by trailers are added to merge commit messages.

Here is the current process for gathering props when a WordPress release approaches:

  • Use git shortlog to dump commit data into a text file. For 5.9, the command was git shortlog -sen v10.8.0...v11.9.0 > 5-9-gutenprops.txt
  • Use git log to dump commits with Co-authored-by trailers into a text file. For 5.9, the command was git shortlog -sen v10.8.0...v11.9.0 > 5-9-co-authored-gutenprops.txt
  • Grab props for pull requests merged after the final Gutenberg release included that have been backported. This is usually done manually, but could maybe be accomplished using git shortlog in the respective wp/X.X branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch". (provided the commits were cherry picked correctly) and repeating the Co-authored-by step above for that branch.
  • Manually merge the three lists while combining duplicates.
  • Match all GitHub contributors with their WordPress.org account. This can be semi-automated for contributors that have linked their .org and GitHub accounts but still requires manual interaction as many folks have not linked their accounts (but please everyone, link your accounts).
  • Merge this list into the Trac/SVN props list generated in the previous section, combining duplicates.

Finalizing Props List

After both processes are completed above, the release squad will attempt to manually verify that contributors with non-code contributions are also represented in the list.

Pain Points

In summary, these are the pain points for collecting props from GitHub:

  • Highly manual and time consuming.
  • Often requires multiple people to divide and conquer username matching (especially when a contributor has not linked their w.org account to their GitHub one).
  • Non-code contributions never receive props, unless a Co-authored-by trailer is added or they are added during the finalization step.
  • The contributions of all contributors are often under-represented, if not missed entirely.
  • Contributions are sometimes double-counted when the Core committer also compiles props for the package update commit (see [52633] as an example).
  • Props counts for the Trac/SVN side are often higher than the GitHub side because of better tracking with SVN commit messages and respective prop guidelines.

Proposed Changes to GitHub Processes

The following change is recommended to standardize and improve the process of giving all community members props for their contributions.

When a Gutenberg pull request is merged, the contributor merging changes into the code base will be responsible for reviewing the PR, and any associated issue(s) or draft/closed PRs to identify all contributors who should be credited on the merge commit by following the same process and guidelines as WordPress Core SVN and adding a “Props user1, user2, user3.” line in the merge commit message.

The same guidelines should be followed as SVN commits. They’re listed below for clarity with new lines specific to GitHub in bold, and irrelevant items specific to w.org omitted:

  • Must be preceded by a blank line.
  • GitHub usernames should be used, not WordPress.org usernames.
  • Usernames must not start with an @ (at) sign.
  • Separate usernames by comma + space. Think: /^props (\s*([^,]+),?)+$/
  • Copy/paste usernames to avoid typos.
  • Err on the side of giving props liberally. Props provide major encouragement for contributors.
  • If you forget to prop someone, check to see if they already have props in the current release as it won’t matter in the long run as they’ll be included in the release credits anyway. If they aren’t already propped, you can flag it to the Release Coordinator to ensure that person is added on release day. It’s also recommended to reach out to the contributor in SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. or in a comment on the ticket as a courtesy and apologize for missing their name in the commit message and letting them know their contribution will be recognized and note how.

Pros

  • Allows for manually auditing the list of contributors. This helps give proper credit to testers, bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. reporters, and other non-code contributors and also prevents giving props to anyone that does not positively contribute to the solution.
  • Consistency between SVN and GitHub
  • Allows the same w.org props script to be adapted and used for GitHub props, greatly reducing the amount of manual work required. https://profiles.wordpress.org/github:username can be used to easily look up a GitHub contributor’s w.org username (provided they have linked their accounts). Example: https://profiles.wordpress.org/github:desrosj.

Cons

  • Requires the merging contributor to manually compile a list of contributors (though this same con exists on SVN wherein the committer needs to compile the list from Trac).
  • Does not show up on user contribution graphs in GitHub.

Note: for the immediate near-term, this change is proposed for the Gutenberg repository. However, this policy is encouraged to be considered on a repository by repository basis for all GitHub repositories under the WordPress organization that are synced into SVN unless an acceptable alternate policy is in place.

Why not the Co-authored-by trailer?

On the surface, the Co-authored-by trailer seems like the ideal solution, and even shows up on a contributor’s profile activity feed. However, there are several shortcomings.

  • It’s GitHub-specific. If there’s a need to use another GITGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/. service in the future, the process for giving props would need to be revised.
  • Co-authored-by trailers can only be added to commit messages easily when using GitHub Desktop. When merging a pull request through the website, the merging contributor still needs to manually compile a list of names and emails for anyone that contributed.
  • This method includes emails in the commit message. While users can choose to keep their email address private in their GitHub settings and emails are accessible through git log, making an email to reach out to a specific contributor more easily accessible is not ideal.
  • Emails and legal and preferred names change. Usernames are far less likely to change.
  • Since commit subject lines only are used when squashing and merging pull requests, the Co-authored-by trailers found within any commit message on a PR are stripped out of the final commit message. The merging contributor needs to re-add them and manually look through each commit for Co-authored-by trailers.

Other Potential Solutions Ruled Out

Next Steps

After discussing this proposal, fielding all questions, and addressing all concerns, these are the next steps required:

  1. Educate the maintainers of the Gutenberg repository and help them make this adjustment in their workflow.
  2. Add merge commit details to Gutenberg’s Repository Management > Merging Pull Requests documentation.
  3. Update the Core handbook page for Preparing the About Page > Props documentation.
  4. Update the Core handbook page for Commit Messages, referencing the Gutenberg Merging Pull Requests documentation.
  5. Adjust the script on w.org responsible for compiling the list fo props for a release to also ingest a git log with GitHub usernames.
  6. Explore potential ways to automate props collecting with GitHub Actions (a workflow that collects all participants for the pull request and attached issues, etc.).

Other Resources

  • MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. tickets for gathering Gutenberg props: 5.7, 5.6, 5.5, 5.4, 5.3, 5.2, 5.0.

Props @jeffpaul, @sergeybiryukov, @cbringmann for pre-publish review.