On WordPress + Git

Can you believe it – we’ve made it through a State of the Word without anybody asking “when is WordPress moving to Git/GitHub?” You may, however, have caught a brief mention of issue trackers in relation to the Triage Team focus for 2019. While it’s very important to make the distinction between Git the version control system (VCS) and GitHub the service, as the answer usually goes, it’s understandably a continued area of interest. Many parts of WordPress have been developed using GitHub as the central tool, along with countless plugins and themes and even the WordPress book.

Here’s the tl;dr (but you should definitely keep reading after this): Changing things up doesn’t just mean “let’s make the GitHub mirror at WordPress/wordpress-develop the canonical and migrate Trac tickets over” – it means imagining what kind of change would be a net benefit to the core development process and eventually the entire .org ecosystem, and then finding the right tools to do it.

To that end, there is a group of people including myself (@helen), @desrosj, and @omarreiss who have been and will continue to be doing more coordinated research and planning around tooling. There is no current planned timeline nor is this a priority on top of the projects already enumerated for 2019, but any potential tooling change is being evaluated as it potentially relates to those projects, especially if it can better support phase 2 of Gutenberg development and the Triage Team.

This is not about chasing the latest and greatest or evangelizing a preference – it’s important to identify the goals we have for the project and what pain points we are experiencing. More specifically than “democratizing publishing”, in the core development process we should be aiming for diverse participation, a faster-but-steady pace of development, predictable and timely feedback cycles, and continuing to build user trust among users of all types. Recent pain points have been merges between branches (especially 5.0 back to trunk), JavaScript package updating, and continued participation when projects move from plugins and GitHub into core and Trac.

Roughly, here are some early thoughts on various moving pieces and potential future improvements.

Repositories and Workflows

  • SVN repositories would need to remain, essentially flipping the mirroring process to go from Git -> SVN, making SVN (and Git) repos on .org read-only
  • Should the core build process continue to be handled as-is or should we move to something like Travis?
  • Integration of more automated testing – visual regression, end-to-end, accessibility, performance
  • Identification of the ideal lifecycle of an issue and process for a pull/merge request – design, docs, review, testing, etc.
  • Identification of contribution workflows (contributor documentation, Git branching methodology, etc.)
  • Security tracking and releasing

Issue Tracker

  • Critical for a Triage Team to review existing issues and to remain active going forward
  • Potential for the bulk triage process to include migration from Trac to another tracker
  • Any issue migration should be determine on a case by case basis by the Triage Team in collaboration with component maintainers; the most automation that should happen is a tool that takes a list of Trac tickets and imports them elsewhere
  • Issue import process needs to take commenter attribution into account
  • Trac would remain in a read-only state
  • How are reports generated and used (i.e. is the built-in filtering capability enough in a given tool or will we need something more robust to support workflows)
  • Is the issue tracker still the best place for feature requests?
  • Implementation of issue templates
  • Identifying existing custom integrations and whether those problems still exist and still need to be solved after a move

Broader Ecosystem (later / bigger question mark)

  • Connectors from GitHub to .org plugin and theme repos (GitHub Actions-powered build+deploy)
  • Automated testing – sniffers, Tide, unit tests, WP and PHP compat testing, Theme Check
  • Aligning plugin and theme review teams

#git, #trac, #triage

Guideline reminder: commenting and comment moderation

With many new observers and contributors joining the WordPress core project recently, let’s take a moment to review the comment guidelines for Make/Core, which can also be extended to apply to Make/Design, Make/Accessibility, and Core Trac. Overall, the majority of comments seen are positive and constructive, and it’s important to keep it that way to ensure the health of the project and its contributors.

Of particular note to editors is the comment moderation policy:

If a comment is disrespectful and/or unprofessional, it may be edited at the discretion of the core team.

Editing of a comment will be done with the approval of at least two blog administrators. When a comment is edited, only the offending section will be edited with the intent of retaining as much of the expressed opinion. The administrators who edit the offending comment will add an editor’s note stating the reason for editing and the names of the administrators who took action. Additionally, the administrator doing the editing should retain a screenshot of the unedited comment, which can be uploaded to the Media Library on make/core, if necessary.

Comments will only be deleted when the offending comment is clearly spam that was not properly moderated.

Comments are generally approved by default, which means that email notifications are triggered immediately. Outright deletion of a comment that is anything except obvious spam will be noticed and fosters justified feelings of undue censorship and lack of consideration. Comments with issues such as information that should be privately sent to the security team, attacks on individuals, excessive use of profanity, or distractingly off-topic content should be edited with a note per the process outlined above. This serves multiple purposes: a record of what was changed and why; a visible stand by contributors that the cited behavior is not tolerated; and a public record of that particular commenter’s behavior for others to use as context.

There is a quiet RC2 now available it…

There is a quiet RC2 now available – it is a fair number of commits (50+), so please take a look through those and test as you can.

#4-7

Starter content for themes in 4.7

One of the hardest things for people setting up sites with WordPress for the first time is understanding what themes are and how a given theme can work for you, especially when there’s no content there to visualize. There are also significant gaps between local theme previews, screenshots, and .org previews. Even when there are easy-to-use site customization tools, it is difficult to figure out where to start and what things are going to be like.

To help users along that path, 4.7 introduces the concept of “starter content” – theme-specific selections of content to help showcase a theme to users and serve as a starting point for further setup of new sites. Starter content works especially well in tandem with visible edit shortcuts, allowing users to not only see what content might work best where within a theme, but from there to be able to jump to building off of that base without having to initially spend time figuring out, say, which widgets areas map where.

How it works

Starter content is applied and displayed upon entering the customizer, with no changes appearing on the live site until customizer changes are explicitly saved and published. In 4.7, this initial view of a theme with starter content will only happen for “fresh sites” – new installs that have not yet had any posts, pages, widgets, or customizer settings updated. This state is indicated in the fresh_site option with a value of 1. The current limitation is in line with prioritizing initial site setup for this release, and allows for themes to begin implementing content and ensuring that there is a solid base before introducing more complicated logic and UI to “merge” starter content with existing content in a future release (#38624). That being said, if two themes in a given fresh site both have starter content, if the starter content from the first theme is applied and you make some changes to that starter content, when you switch to the second theme the starter content from that theme will override the starter content from the first theme only for the settings which have not been modified. Also remember that theme mods are always theme-specific, so starter content for theme switches will never be copied.

Core provides a set of content that themes can select from (technical details below). These include a variety of widgets, pages, and nav menu items (including references for the pages), along with the ability to provide attachments, theme mods, and options. Any included images for attachments need to be from within a theme or plugin folder and cannot be loaded from an external URL. Twenty Seventeen will ship with starter content enabled; there are no plans to add the functionality to past default themes.

How to use it

Themes define a subset of core-provided starter content using add_theme_support() – let’s look at a breakdown of how Twenty Seventeen does things. In its setup function hooked to after_setup_theme, we see an array with collections of widgets, posts (pages), attachments, options, theme mods, and nav menus registered as the starter content. The customizer looks for this starter-content at after_setup_theme priority 100, so do make this call at that point or later:

add_theme_support( 'starter-content', array( /*...*/ ) )

Widgets

Each widget area ID corresponds to one sidebar registered by the theme, with the contents of each widget area array being a list of widget “symbols” that reference core-registered widget configurations. Most default widgets are available (archives, calendar, categories, meta, recent-comments, recent-posts, and search), as well as text widgets with business hours (text_business_info) and a short prompt for an “about this site” style blurb (text_about). Themes should place widgets based on what works best in that area – for instance, business info in a footer widget of a business-centric theme, or a nicely styled calendar widget in the sidebar of a blog.

Custom widgets can also be registered at the time of starter content registration or later filtered in, which will be more likely the case for plugins, as add_theme_support() for starter content will be overridden by any later calls.

// Custom registration example
add_theme_support( 'starter-content', array(
	'widgets' => array(
		'sidebar-1' => array(
			'meta_custom' => array( 'meta', array(
				'title' => 'Pre-hydrated meta widget.',
			) ),
		),
	),
);

// Plugin widget added using filters
function myprefix_starter_content_add_widget( $content, $config ) {
	if ( isset( $content['widgets']['sidebar-1'] ) ) {
		$content['widgets']['sidebar-1']['a_custom_widget'] = array(
			'my_custom_widget', array(
				'title' => 'A Special Plugin Widget',
			),
		);
	}
	return $content;
}
add_filter( 'get_theme_starter_content', 'myprefix_starter_content_add_widget', 10, 2 );

Posts (Pages)

Like widgets, core provides posts which can be referenced by symbols; all six currently in the core set are pages, but the starter content API can support various post types (including attachments, which are defined and handled separately). The symbols for the core-provided pages as of 4.7 are home, about, contact, blog, news, and homepage-section. The pages references by blog and news are both empty in the content area and are meant to be assigned as the page for posts (detailed with options below). Imported posts can further be used as post IDs when referenced using the symbol of the item within double curly braces, e.g. {{home}} for the static front page option.

Posts, like widgets, are also easily customizable, either by overriding specific fields for a predefined item or by defining a new custom one entirely. The available fields are post_type, post_title, post_excerpt, post_name (slug), post_content, menu_order, comment_status, thumbnail (featured image ID), and template (page template name, as would be stored in post meta).

// Overriding/supplementing a predefined item plus a custom definition
add_theme_support( 'starter-content', array(
	'posts' => array(
		'about' => array(
			// Use a page template with the predefined about page
			'template' => 'sample-page-template.php',
		),
		'custom' => array(
			'post_type' => 'post',
			'post_title' => 'Custom Post',
			'thumbnail' => '{{featured-image-logo}}',
		),
	),
);

Attachments

While attachments are post objects, they have special handling due to the sideloading of specified media. Media must be loaded from within the theme or plugin directory – external URLs are currently disallowed for performance reasons. The location of the media, either as a full file path or relative to the theme root, is indicated in the file array item, and some other post fields are available, with post_content mapping to description and post_excerpt to caption. Imported attachments can further be used by using their respective array keys as symbols used within double curly braces, e.g. {{featured-image-logo}} as the featured image (thumbnail) for a post. In the example below, an attachment is specified and used as the featured image for the about page.

add_theme_support( 'starter-content', array(
	'attachments' => array(
		'featured-image-logo' => array(
			'post_title' => 'Featured Logo',
			'post_content' => 'Attachment Description',
			'post_excerpt' => 'Attachment Caption',
			'file' => 'assets/images/featured-logo.jpg',
		),
	),
	'posts' => array(
		'about' => array(
			// Use the above featured image with the predefined about page
			'thumbnail' => '{{featured-image-logo}}',
		),
	),
);

Nav Menus

Nav menus are also specially treated post objects. There are essentially two types of nav menu items – custom links, which require a title and url, and object references, which require type, object, and object_id, which can be a {{post}} symbolic reference.

Options and Theme Mods

Options and theme mods are more freeform and merely require a match for a name. Symbolic references to imported items are particularly useful here, such as for the page_on_front option and Twenty Seventeen’s multi-section homepage as stored in theme mods. Themes hosted on .org will likely be limited to theme mods and a subset of options; all other developers are encouraged to consider user experience and expectations first.

What does this mean for themes?

Core-provided content helps support a consistent preview experience across themes with high quality localized content, helping users understand how WordPress and that theme fit their needs. Theme authors are encouraged to select from core-provided content, but as is always the case with WordPress, starter content still has some flexibility, and will continue to mature as a feature over time.

While theme review guidelines need to be finalized and documented, it is anticipated that themes being submitted to WordPress.org will be expected to select from core-provided content to promote consistency and to help keep the theme review process from becoming lengthier, with exceptions being made on a case by case basis. Themes being distributed outside of WordPress.org are not subject to the same review process; however, it is recommended that consistent user experiences be the primary consideration in how starter content is chosen and implemented.

What’s next?

Testing this feature with your theme or plugin does not require a fresh install every time – you can set the fresh_site option to 1 using the tool of your choice, such as wp-cli or phpMyAdmin. Do note that content merging logic has not been tackled so you may not quite get the exact same effect as a truly fresh install; however, since all of the changes are held in a customizer changeset and are not otherwise live on the site, there is no data loss, unless you save and publish the starter content overrides of course.

In the future, all sites should be able to live preview new themes in ways that really showcase that theme’s capabilities, whether that’s with no content made yet or with a lot of existing content to work into the preview. This will take a lot of consideration around user expectations for content merging, and should be tackled as its own feature. There are also potentially interesting extensions such as UI for users to select from sets of content or selectively accept/reject staged changes.

And finally, to best align preview experiences in various places, theme previews on .org should also leverage starter content. Helping hands are needed here – please ping me (@helen) in Slack should you be interested!

#4-7, #dev-notes

Dev Chat Agenda for November 16 (4.7 week 13)

This is the agenda for the weekly dev meeting on November 16, 2016 at 21:00 UTC:

  • Meeting reminder: Weekly chat has been moved one hour later to 21:00UTC.
  • Schedule reminder: Tomorrow is the target for RC! RC means the list of tickets should be at zero (with the exception of the about page), as a release candidate is supposed to represent software you believe you can release. It is currently at 24.
  • Ticket reminder: For any tickets you’ve moved into the milestone, please get these resolved in the next day.
  • Dev notes:  These should all be published this week, with a collective field guide forthcoming from @aaronjorbin.
  • Getting ready for RC with a 4.7 open ticket scrub

If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

#4-7, #agenda, #dev-chat

4.7 beta and RC plans

To push us to get tickets resolved and take advantage of some shifting in my own schedule, I’d like to propose that we work quickly toward a beta 4 on Monday (November 14) and move RC back from Tuesday to Thursday (November 17). There are still 31 tickets open; I would like to get to 15 or below by beta 4, and the only one that should be open when we get to RC is the one for the about page. Be on the lookout for ad hoc scrubs and pings over the next week 🙂

As a reminder, a release candidate should represent the software that we believe will ship, with any commits coming during the RC period being limited to regressions and serious bug fixes in new features. 4.7 will be branched off once we get to RC, at which time guest committers may continue to commit to trunk, but any merges back to the 4.7 branch must be done by a permanent committer with the additional review of another permanent committer (which includes lead developers).

#4-7

Dev Chat Agenda for October 19 (4.7 week 9)

This is the agenda for the weekly dev meeting on October 19, 2016 at 20:00 UTC:

If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

#4-7, #agenda, #dev-chat

Dev Chat Agenda for October 12 (4.7 week 8)

This is the agenda for the weekly dev meeting on October 12, 2016 at 20:00 UTC:

If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

#4-7, #agenda, #dev-chat

The Road to 4.7 Beta 1

For the last 55 days, trunk has been in an alpha state and open for all commits. In 15 days this will change and the first beta for 4.7 will be released. During beta, no new enhancements or feature requests should be committed to WordPress core. While some may desire to wait for just one more thing, that is a rabbit hole which is inconsistent with the WordPress philosophies. Here is a list of things that need to happen during the next 15 days in order to get ready for Beta 1 on October 26th.

The deadline for merging feature projects into WordPress core is in 8 days. There are currently three proposals for projects to merge published with several additional proposals actively being worked on. All committers and active contributors should review these proposals (I’ll add links to additional proposals when they are made):

There are 60 enhancements and feature requests milestoned for 4.7.  Of these, 21 have no owner.  At the end of this week, all enhancements and feature requests without an owner will be punted.  Tickets will also be regularly evaluated this week.  Over the next two weeks, tickets will be evaluated during both scheduled and unscheduled bug scrubs, and tickets not moving forward will be removed from the milestone. The next scheduled bug scrub will be at Wednesday, October 12, 2016 17:00 UTC.

During this week’s dev chat, we will discuss all the proposals that have been made thus far. If additional meetings for considering any of the proposals before the merge deadline are needed, this will be decided then.

#4-7, #proposal

Dev Chat Agenda for October 5 (4.7 week 7)

This is the agenda for the weekly dev meeting on October 5, 2016 at 20:00 UTC:

If you have anything to propose to add to the agenda or specific items related to the above, please leave a comment below. See you there!

#4-7, #agenda, #dev-chat