Make README.md canonical, generating readme.txt at build time

.gitignore

@@ -6,3 +6,6 @@
 *.zip
 /wp-includes/js/workbox*
 /wiki
+
+# Generated via bin/transform-readme.php
+/readme.txt

Gruntfile.js

@@ -21,15 +21,15 @@ module.exports = function (grunt) {
 				stdout: true,
 				stderr: true,
 			},
-			readme: {
-				command: 'npm run generate-readme', // Generate the readme.md.
-			},
 			phpunit: {
 				command: 'phpunit',
 			},
 			verify_matching_versions: {
 				command: 'php bin/verify-version-consistency.php',
 			},
+			transform_readme: {
+				command: 'php bin/transform-readme.php',
+			},
 			install_workbox: {
 				command:
 					'if [ -e wp-includes/js/workbox* ]; then rm -r wp-includes/js/workbox*; fi; npx workbox copyLibraries wp-includes/js/',
@@ -46,7 +46,7 @@ module.exports = function (grunt) {
 				options: {
 					plugin_slug: 'pwa',
 					build_dir: 'build',
-					assets_dir: 'wp-assets',
+					assets_dir: '.wordpress-org',
 				},
 			},
 		},
@@ -61,8 +61,6 @@ module.exports = function (grunt) {
 	// Register tasks.
 	grunt.registerTask('default', ['build']);
 
-	grunt.registerTask('readme', ['shell:readme']);
-
 	grunt.registerTask('build', function () {
 		const done = this.async();
 		const spawnQueue = [];
@@ -102,21 +100,24 @@ module.exports = function (grunt) {
 				.trim()
 				.split(/\n/)
 				.filter(function (file) {
-					return !/^(\.|bin|([^/]+)+\.(json|xml)|Gruntfile\.js|tests|readme\.md|CONTRIBUTING\.md|wp-assets|composer\..*|webpack.*)/.test(
+					return !/^(\.|bin|([^/]+)+\.(json|xml)|Gruntfile\.js|tests|README\.md|CONTRIBUTING\.md|\.wordpress-org|composer\..*|webpack.*)/.test(
 						file
 					);
 				});
+
+			grunt.task.run('shell:transform_readme');
+			paths.push('readme.txt');
+
 			paths.push('wp-includes/js/workbox*/**');
 
 			grunt.task.run('clean');
-			grunt.task.run('readme');
 			grunt.config.set('copy', {
 				build: {
 					src: paths,
 					dest: 'build',
 					expand: true,
 					options: {
-						noProcess: ['*/**', 'LICENSE'], // We only want to process pwa.php, readme.txt, and readme.md.
+						noProcess: ['*/**', 'LICENSE'], // We only want to process pwa.php and README.md.
 						process(content, srcpath) {
 							let matches, version, versionRegex;
 							if (/pwa\.php$/.test(srcpath)) {

readme.md → README.md

@@ -1,20 +1,21 @@
-<!-- DO NOT EDIT THIS FILE; it is auto-generated from readme.txt -->
 # PWA
 
-![Banner](wp-assets/banner-1544x500.png)
+![Banner](.wordpress-org/banner-1544x500.png)
+
 WordPress feature plugin to bring Progressive Web App (PWA) capabilities to Core
 
 **Contributors:** [google](https://profiles.wordpress.org/google), [xwp](https://profiles.wordpress.org/xwp), [westonruter](https://profiles.wordpress.org/westonruter), [albertomedina](https://profiles.wordpress.org/albertomedina)  
 **Tags:** [pwa](https://wordpress.org/plugins/tags/pwa), [progressive web apps](https://wordpress.org/plugins/tags/progressive-web-apps), [service workers](https://wordpress.org/plugins/tags/service-workers), [web app manifest](https://wordpress.org/plugins/tags/web-app-manifest), [https](https://wordpress.org/plugins/tags/https)  
 **Requires at least:** 5.5  
-**Tested up to:** 5.6  
+**Tested up to:** 5.7  
 **Stable tag:** 0.6.0  
 **License:** [GPLv2 or later](http://www.gnu.org/licenses/gpl-2.0.html)  
-**Requires PHP:** 5.6  
+**Requires PHP:** 5.6
 
-[![Build Status](https://github.com/GoogleChromeLabs/pwa-wp/workflows/Build,%20test%20&%20measure/badge.svg)](https://github.com/GoogleChromeLabs/pwa-wp/actions?query=branch%3Adevelop+workflow%3A%22Build%2C+test+%26+measure%22) [![Built with Grunt](https://gruntjs.com/cdn/builtwith.svg)](http://gruntjs.com)
+[![Build Status](https://github.com/GoogleChromeLabs/pwa-wp/workflows/Build,%20test%20&%20measure/badge.svg)](https://github.com/GoogleChromeLabs/pwa-wp/actions?query=branch%3Adevelop+workflow%3A%22Build%2C+test+%26+measure%22)
+[![Built with Grunt](https://gruntjs.com/cdn/builtwith.svg)](http://gruntjs.com)
 
-## Description ##
+## Description
 
 <blockquote cite="https://developers.google.com/web/progressive-web-apps/">
 Progressive Web Apps are user experiences that have the reach of the web, and are:
@@ -46,11 +47,10 @@ Documentation for the plugin can be found on the [GitHub project Wiki](https://g
 
 **Development of this plugin is done [on GitHub](https://github.com/GoogleChromeLabs/pwa-wp). Pull requests welcome. Please see [issues](https://github.com/GoogleChromeLabs/pwa-wp/issues) reported there before going to the [plugin forum](https://wordpress.org/support/plugin/pwa).**
 
-## Frequently Asked Questions ##
+## Frequently Asked Questions
 
 Please see the [frequently asked questions](https://github.com/GoogleChromeLabs/pwa-wp/wiki/FAQ) on the GitHub project wiki. Don't see an answer to your question? Please [search the support forum](https://wordpress.org/support/plugin/pwa/) to see if someone has asked your question. Otherwise, please [open a new support topic](https://wordpress.org/support/plugin/pwa/#new-post).
 
-## Changelog ##
+## Changelog
 
 For the plugin’s changelog, please see [the Releases page on GitHub](https://github.com/GoogleChromeLabs/pwa-wp/releases).
-

bin/transform-readme.php

@@ -0,0 +1,135 @@
+#!/usr/bin/env php
+<?php
+/**
+ * Rewrite README.md into WordPress's readme.txt
+ *
+ * @codeCoverageIgnore
+ * @package PWA
+ */
+
+// phpcs:disable WordPress.WP.AlternativeFunctions.file_system_read_fwrite
+// phpcs:disable WordPress.WP.AlternativeFunctions.file_get_contents_file_get_contents
+// phpcs:disable WordPress.WP.AlternativeFunctions.file_system_read_file_get_contents
+// phpcs:disable WordPress.WP.AlternativeFunctions.file_system_read_file_put_contents
+
+if ( 'cli' !== php_sapi_name() ) {
+	fwrite( STDERR, "Must run from CLI.\n" );
+	exit( __LINE__ );
+}
+
+$readme_md = file_get_contents( __DIR__ . '/../README.md' );
+
+$readme_txt = $readme_md;
+
+// Transform the sections above the description.
+$readme_txt = preg_replace_callback(
+	'/^.+?(?=## Description)/s',
+	static function ( $matches ) {
+		// Delete lines with images.
+		$input = trim( preg_replace( '/\[?!\[.+/', '', $matches[0] ) );
+
+		$parts = preg_split( '/\n\n+/', $input );
+
+		if ( 3 !== count( $parts ) ) {
+			fwrite( STDERR, "Too many sections in header found.\n" );
+			exit( __LINE__ );
+		}
+
+		$header = $parts[0];
+
+		$description = $parts[1];
+		if ( strlen( $description ) > 150 ) {
+			fwrite( STDERR, "The short description is too long: $description\n" );
+			exit( __LINE__ );
+		}
+
+		$metadata = array();
+		foreach ( explode( "\n", $parts[2] ) as $meta ) {
+			$meta = trim( $meta );
+			if ( ! preg_match( '/^\*\*(?P<key>.+?):\*\* (?P<value>.+)/', $meta, $matches ) ) {
+				fwrite( STDERR, "Parse error for meta line: $meta.\n" );
+				exit( __LINE__ );
+			}
+
+			$unlinked_value = preg_replace( '/\[(.+?)]\(.+?\)/', '$1', $matches['value'] );
+
+			$metadata[ $matches['key'] ] = $unlinked_value;
+
+			// Extract License URI from link.
+			if ( 'License' === $matches['key'] ) {
+				$license_uri = preg_replace( '/\[.+?]\((.+?)\)/', '$1', $matches['value'] );
+
+				if ( 0 !== strpos( $license_uri, 'http' ) ) {
+					fwrite( STDERR, "Unable to extract License URI from: $meta.\n" );
+					exit( __LINE__ );
+				}
+
+				$metadata['License URI'] = $license_uri;
+			}
+		}
+
+		$expected_metadata = array(
+			'Contributors',
+			'Tags',
+			'Requires at least',
+			'Tested up to',
+			'Stable tag',
+			'License',
+			'License URI',
+			'Requires PHP',
+		);
+		foreach ( $expected_metadata as $key ) {
+			if ( empty( $metadata[ $key ] ) ) {
+				fwrite( STDERR, "Failed to parse metadata. Missing: $key\n" );
+				exit( __LINE__ );
+			}
+		}
+
+		$replaced = "$header\n";
+		foreach ( $metadata as $key => $value ) {
+			$replaced .= "$key: $value\n";
+		}
+		$replaced .= "\n$description\n\n";
+
+		return $replaced;
+	},
+	$readme_txt
+);
+
+// Convert markdown headings into WP readme headings for good measure.
+$readme_txt = preg_replace_callback(
+	'/^(#+)\s(.+)/m',
+	static function ( $matches ) {
+		$md_heading_level = strlen( $matches[1] );
+		$heading_text     = $matches[2];
+
+		// #: ===
+		// ##: ==
+		// ###: =
+		$txt_heading_level = 4 - $md_heading_level;
+		if ( $txt_heading_level <= 0 ) {
+			fwrite( STDERR, "Heading too small to transform: {$matches[0]}.\n" );
+			exit( __LINE__ );
+		}
+
+		return sprintf(
+			'%1$s %2$s %1$s',
+			str_repeat( '=', $txt_heading_level ),
+			$heading_text
+		);
+	},
+	$readme_txt,
+	-1,
+	$replace_count
+);
+if ( 0 === $replace_count ) {
+	fwrite( STDERR, "Unable to transform headings.\n" );
+	exit( __LINE__ );
+}
+
+if ( ! file_put_contents( __DIR__ . '/../readme.txt', $readme_txt ) ) {
+	fwrite( STDERR, "Failed to write readme.txt.\n" );
+	exit( __LINE__ );
+}
+
+fwrite( STDOUT, "Validated README.md and generated readme.txt\n" );

bin/verify-version-consistency.php

@@ -19,12 +19,12 @@
 
 $versions = array();
 
-$readme_txt = file_get_contents( dirname( __FILE__ ) . '/../readme.txt' );
-if ( ! preg_match( '/Stable tag:\s+(?P<version>\S+)/i', $readme_txt, $matches ) ) {
+$readme_md = file_get_contents( dirname( __FILE__ ) . '/../README.md' );
+if ( ! preg_match( '/\*\*Stable tag:\*\*\s+(?P<version>\S+)/i', $readme_md, $matches ) ) {
 	echo "Could not find stable tag in readme\n";
 	exit( 1 );
 }
-$versions['readme.txt#stable-tag'] = $matches['version'];
+$versions['README.md#stable-tag'] = $matches['version'];
 
 $plugin_file = file_get_contents( dirname( __FILE__ ) . '/../pwa.php' );
 if ( ! preg_match( '/\*\s*Version:\s*(?P<version>\d+\.\d+(?:.\d+)?(-\w+)?)/', $plugin_file, $matches ) ) {

composer.json

@@ -11,8 +11,7 @@
     "dealerdirect/phpcodesniffer-composer-installer": "0.7.1",
     "phpcompatibility/phpcompatibility-wp": "2.1.1",
     "phpunit/phpunit": "^5.7 || ^6.5 || ^7.5",
-    "wp-coding-standards/wpcs": "2.3.0",
-    "xwp/wp-dev-lib": "1.6.5"
+    "wp-coding-standards/wpcs": "2.3.0"
   },
   "config": {
     "platform": {

package.json

@@ -44,7 +44,6 @@
     "check-engines": "wp-scripts check-engines",
     "check-licenses": "wp-scripts check-licenses --production",
     "deploy": "grunt deploy",
-    "generate-readme": "./vendor/xwp/wp-dev-lib/scripts/generate-markdown-readme && sed -i.bak 's/travis-ci\\.org/travis-ci.com/g' readme.md && rm readme.md.bak",
     "lint": "npm-run-all --parallel lint:*",
     "lint:js": "wp-scripts lint-js",
     "lint:js:fix": "npm run lint:js -- --fix",

phpunit.xml

@@ -1,5 +1,5 @@
 <phpunit
-	bootstrap="vendor/xwp/wp-dev-lib/sample-config/phpunit-plugin-bootstrap.php"
+	bootstrap="tests/bootstrap.php"
 	backupGlobals="false"
 	colors="true"
 	convertErrorsToExceptions="true"