New Commit Message Requirements in Git: Hello Props Bot

Note: This post was updated to correct the format used in one example and remove references to the wapuu w.org username (not officially associated with the project). A note was also added under a list saved as a synced pattern to indicate the contents of the list may change over time. 2/2/2024 – @desrosj

In January 2022, a proposal was published on this blog to implement a new process within any GitHubGitHub GitHub is a website that offers online implementation of git repositories that 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/ repository under the WordPress organization to ensure anyone and everyone contributing to the project receives due thanks in the form of “props.” The post is still almost entirely accurate and it’s recommended you read that in full. Here are some highlights.

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 who 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 12 years, making generating the list of props for each release scriptable and straightforward. The process is 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 yet to be 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.

The post documents the state of props practices and related processes in detail for both Trac/SVN and GitHub. No major changes have been made to these practices since the publish date of that post.

After taking into account all of the feedback received from that proposal, a new policy is now in place for maintainers.

New requirement for 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/ GitHub merge commit messages

Starting today, it is required that GitHub merge commit messages for Gutenberg include credits for all contributors following the same guidance as Core SVN commits:

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.

In Core SVN, this is done as Props x, y, z. In GitHub, this will be done using Co-authored-by trailers. To avoid having personal emails in the commit log of the project (or having to know which personal email someone has associated with their GitHub account at a given time), a contributor’s GitHub and 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/ usernames should be used in the following format:

Co-authored-by: githubusername <dotorgusername@git.wordpress.org>

This practice defines a consistent expected pattern that can be reliably parsed by a script to collect contributions for a repository from a 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/. log in the same fashion as the Core SVN repository.

In order to make this new practice easier for committers and maintainers, a new tool has been merged into the code bases.

Introducing Props Bot

Props Bot is a new GitHub Action that will compile a list of contributors for a given pull request. The bot will leave a comment with a list of contributors formatted for use in both Trac SVN and GitHub.

The comment will be continuously updated as new activity occurs. Additionally, the bot can be manually run by adding the props-bot label to the pull request.

Types of activity included:

• Anyone who publishes commits to the PR’s 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"..
• Anyone who left a review or responded to a review on the PR.
• Anyone who commented on the PR.
• Anyone who created an issue that is attached to the PR.
• Anyone who commented on issues attached to the PR.

As of [57517] in wordpress-develop, and 91450bd in WordPress/gutenberg, Props Bot is now available. 🎉

The bot relies on an active connection between a WordPress.org and GitHub account. For a step-by-step guide on connecting these accounts, please check out the new page in the Core Handbook. 

The bot can be used in any GitHub repository, not just ones under the WordPress organization. However, it’s required for the Gutenberg repository, and official WordPress repositories are strongly encouraged to use it since it will allow the project to appropriately credit contributors in WordPress releases more easily.

What doesn’t Props Bot do?

While the basics of collecting contributors is handled by Props Bot, there are still some things not yet handled by Props Bot:

• Manually include someone who has not directly interacted with the PR or linked issues.
• Contributors who only interact on Trac tickets relevant to the PR need to be manually included.
• Only the first 100 comments are currently checked (see props-bot-action 41).

As a contributor, what do I need to do?

All contributors should confirm that they have connected their GitHub and WordPress.org accounts. There are several ways to confirm this documented on the relevant page in the handbook.

There is one additional step that all contributors should take, even if you have previously connected your accounts.

An added benefit of this new practice is that all props given using this new format will be shown on your GitHub profile’s activity graph. However, this depends on your w.org Git email being added as an alias to your GitHub account (example: desrosj@git.wordpress.org). This can be done by visiting the Settings > Emails page on GitHub. 

Note: You’ll see an orange “unverified” notice next to your @git.wordpress.org email after adding it as an alias in GitHub. In the future, email forwarding may be configured to allow these emails to be verified. See this Making Systems request for more information.

How are unlinked contributors handled?

When unlinked contributors are detected, Props Bot will pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” them in the comment, requesting they establish a connection and link to the handbook page.

Any unlinked contributors are noted in the message provided by Props Bot as a way to associate the person’s contributions with their w.org account should they connect their accounts after the PR is merged. This should be included in the merge commit message.

Contributors without a connected w.org account can not be credited in the w.org Credits APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. and will not have their contributions show up on their GitHub profile.

As a Core 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. or repository maintainer, what do I need to do?

In addition to linking your profiles as described above, a new page has been created in the Core Handbook detailing best practices for Contributor Attribution (“props”). This page collects related information from various parts of the handbook in one location. Please give this page a full read. Below are the specific rules around the new practice:

• The list of Co-authored-by trailers must be preceded by a blank line.
• Co-authored-by trailers should be the last thing in a commit message.
• The unlinked contributors must come before the Co-authored-by trailers.
• Unlinked contributors should be entered in one line preceded by Unlinked contributors:, each one separated by a comma and a space (, ), and a period after the last one. Example: Unlinked contributors: nacin, matt.
• Usernames must not start with an @ (at) sign.
• When manually adding someone, please only use their GitHub and WordPress.org usernames in the following format: Co-authored-by: githubusername <dotorgusername@git.wordpress.org>.
• The only accounts that are allowed to be noted with a non-w.org email are bot accounts (dependabot or github-actions). It’s important to leave these bots as listed by the GitHub generated Co-authored-by trailer so future contributors know which bots were involved in the changes.
• If there are contributors already noted with Co-authored-by in the suggested commit message, verify they are also included in the list provided by Props Bot before removing. These will be in GitHub format and should be converted to the above w.org format. Deleting the GitHub formatted ones will ensure an accurate contributor count for each commit, but it’s not required. Non w.org emails will be ignored by the props parsing scripts.
• If a contributor’s w.org username is unknown, add their GitHub username to the “Unlinked contributors” list.
• If there are Signed-off-by trailers in the suggested commit message, leave them in place above Co-authored-by trailers. These serve a different purpose and are ignored in the context of collecting props.

Note: The above list is a synced pattern. As it’s improved over time, the changes will be reflected in this post. The above list may be different than what was originally published.

Suppose you maintain a repository and want to use this bot in your project. In that case, the repository has an example YAML file with detailed inline documentation that you can copy into your project. Alternatively, you can add the action to one of your pre-existing workflows or submit a Request to Help Implement issue.

Other Notes

Here are a few other notes:

• If you don’t see a Props Bot comment on your PR, you may need to pull in the latest changed in trunk.
• The action does not currently support using the @v1 notation in the value of uses for a step. For now, using trunk is recommended to help test Props Bot.
• The Action has no tests. Contributions are more than welcome!
• Because this practice was not in place during the 6.5 release cycle, the previously documented process will be used one more time. The timing of this change is such that the work for 6.6 in the Gutenberg release is about to begin, giving us an entire release cycle using this process and allowing the 6.6 release to switch to automating props collection from the Gutenberg repository.

Summary

While these changes do not solve contribution tracking for every team, every workflow, and every tool that’s to make WordPress, this new practice, combined with the Props Bot action, will bring a consistent standard and level of attribution that can be parsed more easily across more areas of the project.

This is version 1 of this change. All feedback and testing is welcome. There will likely be some refinements required after wider testing!

A WordPress release is a sum of all the contributions made during each release cycle, and use of this Props Bot will help us more accurately thank every contributor. ❤️

Props for Props Bot Contributions

A post about props would not be complete without some props! Big props go out to @dharm1025 for helping to get the initial code converted from a generic JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. file to a GitHub Action. Thank you to @jeffpaul and @jorbin for working closely to refine the action, create the new handbook pages, modify existing ones as needed, and test the bot. And thanks to @dd32 for creating the underlying w.org API endpoint to return w.org profiles for GitHub usernames making this possible.

Others who provided feedback, historical insight, helped test, or peer reviewed this post: @pento, @talldanwp, @noisysocks, @gziolo, @swissspidy, @youknowriad, @peterwilsoncc, @joemcgill, @chrisdavidmiles, @wpscholar, @annezazu, @chanthaboune, @davidbaumwald, @cbringmann, and @desrosjbot.