Working on Trac Tickets Using GitHub Pull Requests

WordPress development uses SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase., but many contributors prefer to work in 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. through 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. For some contributors, that means working with a cumbersome workflow within TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.. Many contributors create pull requests using their own forks of the official WordPress Develop mirror so that they can use features like continuous integration and inline code commenting. Historically, though, it has been hard to cross-reference between the two systems.

Starting today, an experimental feature has been added to Trac that will let you link GitHub pull requests opened against the official WordPress Develop Git mirror to tickets. This makes GitHub contributions more visible directly in their related Trac tickets and makes collaborating across the two repositories easier. (Better contributor experiences, ftw!)

Note: this is not a signal of any decision to start moving WordPress to Git, GitHub, or GitLab. That is something that is still being explored separately and independent of this feature. There is no further update on that at this time.

How It Works

In GitHub

  • Fork the official WordPress Develop mirror on GitHub.
  • Create a 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". on your fork, work on your changes, commit, and push.
  • Open a PR to wordpress-develop with the full URLURL A specific web address of a website or web page on the Internet, such as a website’s URL for the Trac ticketticket Created for both bug reports and feature development on the bug tracker. in the PR body. For example “See”.

In Trac

  • The PR will be displayed below the attachments area on tickets with the following information:
    • How many lines were modified
    • Status of the PR checks (Draft/Closed, Travis CI, merge conflicts, etc.)
    • A button to view the PR
    • A button to view the raw diff
  • A bot comment will be added to the ticket’s timeline of events indicating when the ticket was mentioned and where.
  • Every time the PR receives a comment, a PR bot will post the comment onto the Trac ticket.
A screenshot of a WordPress Core Trac ticket with the new linked Pull Requests between the ticket attachments and comments.
Pull requests show between Attachments and Change History.

Important Notes

Trac remains the source of truth for all discussion. If you prefer to continue working in Trac, that’s OK! Nothing will change on Trac itself other than what is noted above. Nothing about how you contribute has to change!

When the PR bot syncs comments over to Trac, it will not trigger an email notification to the subscribers of the Trac ticket. For this reason, it is recommended to provide some type of ticket update in Trac itself. Most likely there will be a need to update the keywords anyway (add has-patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing. or needs-testing, etc.).

Comments made during a code review on the PR will not be posted to the Trac ticket. These comments are usually specific to the code being reviewed, so this should be OK. If this causes confusion, syncing these can be explored.

No changes to WordPress CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. will be merged through GitHub pull requests. This is not new and remains the same. This feature is meant to make contributions done through PRs on GitHub more transparent in Trac.

Pull requests on GitHub are not monitored. No one will be checking for new pull requests regularly. Pull requests must be attached to a Trac ticket to be considered for inclusion in WordPress Core.

Clean up after yourself occasionally. Right now, PRs are not automatically closed when the associated Trac ticket is resolved. If you open a PR, do your best to close PRs that have been merged into Core whenever you are able to.

And finally, this is an experiment. There will likely be some small bugs and things that can be improved since this is the first iteration. Please open up tickets in Meta Trac for any issues that you find. All feedback is welcome! Please leave your thoughts in the comments of this post below.

Props go out to @noisysocks, @pento, @desrosj, @andraganescu, @isabel_brison, and @talldanwp for working on the initial iteration of this feature, @dd32 for heavily overhauling for and deployingDeploy Launching code from a local development environment to the production web server, so that it's available to visitors. to production, and @chanthaboune for helping to proof read this post.