Community Summit Discussion Notes: Unifying development tooling for contribution

From the schedule session:

Today, the local development tooling for contribution to WordPress is fragmented. Contributors use tools such as VVV/Vagrant, Docker, and Playground, but each have limitations and may not be endorsed for contributions. Additionally, some tools require specific set ups, making it challenging for contributors to get started. This discussion will explore how we can unify tooling to provide clarity around recommended tooling and process for contributors.

Facilitator: Aaron Jorbin (@jorbin)

Notetaker 1: Weston Ruter (@westonruter)

Notetaker 2: Emma Sophie Young (@emmaht)

Raw Notes:

• Development Tooling that people use for Contributing
  • VVV
  • Grunt
  • WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/
  • PHPCSPHP Code Sniffer PHP Code Sniffer, a popular tool for analyzing code quality. The WordPress Coding Standards rely on PHPCS.
  • Local Docker Environment
  • Official Docker environments
  • wp-env
  • XAMP
  • D-Dev
  • MAMP
  • Lando
  • wp-scripts
  • Homestead
  • Local WP
  • SVNSVN Apache Subversion (often abbreviated SVN, after its command name svn) is a software versioning and revision control system. Software developers use Subversion to maintain current and historical versions of files such as source code, web pages, and documentation. Its goal is to be a mostly compatible successor to the widely used Concurrent Versions System (CVS). WordPress core and the wordpress.org released code are all centrally managed through SVN. https://subversion.apache.org/.
  • Playground
  • grunt-patch-wordpress
  • 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/.
  • 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/ (& Desktop)
  • TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/.
  • VS Code
  • Tower
  • PhpStorm
  • Vim
  • Sublime Merge
  • Linux
  • Dash
  • Snippets
  • GitHub Co-pilot
  • InstaWP
  • ChatGPT
  • 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/.
  • Matrix
  • Prettierfier
  • SASS
  • JSHint/ESLint
  • QUnit
  • PHPUnit
  • Playwright
  • Behat
  • Composer
  • GitHub Actions
• There are a lot of tools. It’s a broad problem area.
• There are tools that fit into groupings. Tools for local development. Tools for improving quality of code. There are tools for writing code, collaborating. There are lots and lots of tools.
• We need to be specific about what tooling we’re talking about. Are there tools we can consolidate? Can we make official recommendations for our contributors? Can we reduce fragmentation in WP CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. vs 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/?
• What tools are appropriate for first-time contributors vs experienced contributors?
• There is a lot of fragmentation in the official way to contribute: VVV, vs wp-env, vs WP core Docker env, versus official Docker env and our Docker env. Difficult to communicate what the options are. Virtualbox doesn’t work on Mac silicon. What are the tools that we want to get behind and support longer term so we have less fragmentation and better recommendations for senior and beginner contributors? 
• Recently switching development machines was a rude awakening to find things don’t work. We don’t have adequate documentation. We should look at a scale from no-code to code. Make sure we have recommendations for each platform. Currently it’s impossible in our handbook. It’s out there somewhere, but we need to surface it.
• It’s not clear whether we’re talking about core contribution or contributing generally. We should have a way to do easy onboarding for core contribution and pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party development, to use the same tools. We should decouple the required development stack requirements from the specific development tools that provide that stack. Provide a way for someone to use their own stack without having to use core tooling.
• There is a lot of manual tasks being done in the Make teams when new releases are made. For example, a change to the Image blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. requires manual updates across documentation. A lot should be automated.
• The wp-now and playground tools are very promising. These should be integrated more and they should be tried out. They’re very nice. If you’re concerned about object caching and server setup, not the right fit. Great for initial contributors.
  • Contributor dayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. can be bogged down a lot with getting environment set up, and wp-now is a great answer.
• It’s unfortunate that core doesn’t use wp-env. Docker doesn’t always live up to the promise. And wp-env has many layers of abstraction. It would be better if there was more done statically and declaratively. 
• In addition to updating docs, we need someone who can vet changes to the docs.
• For developers who are very beginning, all of this is very overwhelming. Using GitHub Desktop and wp-now, is much more user friendly. Docker requires license when commercial. What do we recommend based on the experience of the user?
• It’s not just that one thing doesn’t work, it’s an issue with specific combinations not working. We need development environments that are more resilient to the unicorn machines that devs actually use.
• Common themes:
  • Documentation: overall space of documentation and its fragmentation
  • Onboarding new contributors and tooling
  • Automation: better supporting teams and each other
  • Question of linking to 3rd party tools, perhaps commercial ones, in the handbook
• GitHub Codespaces exists in trunk right now, and we should document work on experimentation so that people can test them out to see if they are good fits and what to expect.
• Linking to 3rd party tools in our handbook documentation
  • There is always an 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. solution for every proprietary commercial solution. Research has to be done to see what open solution can be recommended. The more open source solutions we find the more creativity can exist as feature suggestions are made.
  • There an official policy for linking to 3rd party resources: it’s clearly allowed to link to official docs for PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php., Linux, Mozilla, or official open source docs. Anything beyond these have to be discussed. 
  • WordPress should never recommend that someone spend money to get tools to contribute to WordPress.
  • If we decide no commercial links, we have to make sure we document clearly how to do it with open tools.
  • WP-CLI has a page that lists hosts that support it.
  • Policy to not recommend any specific theme or plugin, as otherwise it is an endless discussion for what one is recommended and another isn’t.
  • Free open source versus closed source tooling, better to prefer former.
  • Is it OK to just name a commercial resource but not link to it? It’s essentially the same thing. The question is about endorsements generally, not specifically linking.
  • We may still link to free non-open tools, but we’d prefer open tools.
  • Can we ask companies who have non-open tools to open source them? This is what happened with ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/., but we don’t really have capacity to do this for every tool. Perhaps we can be selective about doing it again for other tools.
  • There are ways to do all what we do every day using open source tooling.
  • Is it an issue to link to WordPress.comWordPress.com An online implementation of WordPress code that lets you immediately access a new WordPress environment to publish your content. WordPress.com is a private company owned by Automattic that hosts the largest multisite in the world. This is arguably the best place to start blogging if you have never touched WordPress before. https://wordpress.com/?
  • Opt-ing for closed source may be needed if not user friendly
  • If we did everything as pure as possible on the command line, we wouldn’t get the number of contributors we want.
  • We lean towards not requiring money, and we prefer open source, but the specific line isn’t something we can identify right now.
• Onboarding for new contributor documentation
  • Getting help in support channels for getting set up on Linux environment is very difficult. Documentation is not up to date. 
  • In order to run the software that we’re working on, there are technical requirements. We’ve tried to abstract it away. As a project, we have good incentives to have a very easy pathway to accomplish the task they are working on. We as a project should have an official way to accomplish the minimum tasks that we are asking contributors to do. Currently it seems like there are multiple paths, and we need to smooth it out.
  • The Learn team has pathways for different teams. There is also documentation in the handbooks, but people don’t go to them. Core team could create recordings and structure things in a learnable way. Here we can communicate and collaborate on who to do things. 
  • There are two definitions of new contributors: first time devs and first time WP contributors. We should have a non-tech way to get a novice up and running to contribute.
  • We should do a pro/con list for the options for simple tools. But could we at contributor day get people to actually try out tools with different groups and see what they see, in-person user testing. There is a betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. run of GitHub Codespaces in core; the idea is that we have a devcontainer which works with GitHub Codespaces or Docker or anything. Can we have point people for each tool?
  • We don’t have documented what we want to teach people to use and officially adopt and support, and then document them.
  • wp-now is pretty great, but it is in alpha state; it will crash after 40 hours. Ideally it would eventually replace wp-env. The path would be for the majority to adopt it. We should drive forward wp-now and wp-playground. It can be installed in just seconds. It’s way more efficient than downloading a bunch of docker files.
  • We should make sure we test on different platforms.
  • Even just getting someone to install node and run npm from command line, this is still a big hurdle. A VS Code extension would be great.
  • wp-now is the thing to bet on, but it’s not fully ready yet; someone was working on exposing filesystem in wp-now and be able to tweak things very easily, all in the browser. If Gutenberg could use importmaps, we could have newcomers not just touch PHP files but also JS files. It needs to be as easy to edit a JS file as it is with PHP files.
• Automation
  • Updating documentation
  • Tooling for attribution and props
  • Closing pull requests when they appear completed
  • Codespaces is great because it automatically creates pull requests (playground as well)
  • Pull requests could spin up playground URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org from Gutenberg PR; this would also be useful for wordpress-develop
  • Docs team has a GitHub repo, and they can’t self-assign issues. Automation created which will assign to user who comments. Automation also automatically adds labels. There are a lot of opportunities for automation, but if you don’t know how to automate then you have to do a lot of manual work.
  • Gutenberg also generates changelogs.
  • Any time we can use tooling to reduce the steps it helps people. There’s a lot of delicateness in our processes. 
• Overall documentation on tooling
  • Each Make team needs to own its own documentation and own it. It should live on the make handbook. 
  • What about tools that are used by all teams?
  • It’s hard for people to know where to get started.
  • There is a lack of general overview of all the teams. 
  • There are accounts that contributors need to sign up for. 
  • Make.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//contribute is a contributor orientation tool. This helps route people to teams.
  • For WP-CLI contributor day, they created a handbook page which is changed from contributor day to contributor day. It is updated in real time, it is meant to change, the audience is very clear and specific. They include recommendations for the next contributors day, what you should have set up on your work environment. 
  • It would be great to look at other projects and consider the graphicalness and be more opinionated. We’re selling contribution. We need to keep the documentation up to date and test it on actual installs.
  • If someone is pointed to documentation when they show up at contributor day, that will be a turn off. They need a workshop or something more personal.
• Next steps
  • For documentation for local environments in block editor handbook, which is out of date,  needs suggestions and contributions
  • What needs fresh eyes is the docker environment in wordpress-develop, making sure it still works
  • Pick tools to walk people through at contributor day, and create draft guides to make sure the steps work. (other idea – don’make draft guides and just have fresh eyes approach) – this is also related to the pros/cons list
  • Make engaging first time contributor docs, be welcoming, help them learn something new and be excited to contribute again.
  • Leads of every release should first go through the onboarding process to make sure development environment works.
    • Documentation can make this the next step. To check the last release doc and make sure you can follow it and it makes sense. Start from there.

#summit, #summit-2023