Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add readme.txt transformation from README.md #5815

Merged
merged 4 commits into from
Jan 26, 2021

Conversation

westonruter
Copy link
Member

This is a follow-up on #5807 for #5791.

Relying on the README.md alone had some downsides:

  • We couldn't use a custom title for the GitHub version (e.g. AMP Plugin for WordPress) and had to resort to the ambiguous AMP.
  • The header layout had to be re-ordered so that the description came after the metadata.
  • Embedded videos in the markdown version couldn't have any formatting (such using a linked poster image), resulting in an unsightly bare URL in the markdown version. (And the meta ticket I opened to support videos in markdown is likely not going anywhere.)
  • The formatting of screenshots was not ideal, requiring a <br> between the caption and the image link.
  • While we don't do so currently, we wouldn't be able to use triple-backtick code sections in the markdown version since they aren't supported.

This PR addresses these problems by introducing an automated transformer from README.md to readme.txt as part of the build step. In contrast to before, the readme.txt is not committed to version control, and as such it is no longer needing to be maintained separately.

Before After
image image

Here's the difference between the readme.txt currently on WordPress.org with the new readme.txt that this PR's transformer generates:

11c11
< The Official AMP Plugin, supported by the AMP team. Formerly Accelerated Mobile Pages, AMP enables great experiences across both mobile and desktop.
---
> The official AMP Plugin, supported by the AMP team. Formerly Accelerated Mobile Pages, AMP enables great experiences across both mobile and desktop.
15c15,21
< This official plugin from the AMP project enables AMP content publishing with WordPress in a way that is fully and seamlessly integrated with the standard mechanisms of the platform. The key features are the following:
---
> This official plugin from the AMP project enables AMP content publishing with WordPress in a way that is fully and seamlessly integrated with the standard mechanisms of the platform.
> 
> https://www.youtube.com/watch?v=s52JNMT59s8&list=PLXTOW_XMsIDRGRr5QDffrvND8Qh1RndFb
> 
> For more videos like this, check out the ongoing [AMP for WordPress video series](https://www.youtube.com/playlist?list=PLXTOW_XMsIDRGRr5QDffrvND8Qh1RndFb).
> 
> The plugin's key features include:
60c66
< If you are a developer, we encourage you to [follow along](https://github.com/ampproject/amp-wp) or [contribute](https://github.com/ampproject/amp-wp/blob/develop/contributing.md) to the development of this plugin on GitHub.
---
> If you are a developer, we encourage you to [follow along](https://github.com/ampproject/amp-wp) or [contribute](https://github.com/ampproject/amp-wp/wiki/Contributing) to the development of this plugin on GitHub.

In short, the README.md is now canonical, and the readme.txt is generated from it at build time.

The README.md is basically restored to what we were previously generating from readme.txt:

1d0
< <!-- DO NOT EDIT THIS FILE; it is auto-generated from readme.txt -->
4,5c3,5
< ![Banner](wp-assets/banner-1544x500.png)
< The Official AMP Plugin, supported by the AMP team. Formerly Accelerated Mobile Pages, AMP enables great experiences across both mobile and desktop.
---
> ![Banner](.wordpress-org/banner-1544x500.png)
> 
> The official AMP Plugin, supported by the AMP team. Formerly Accelerated Mobile Pages, AMP enables great experiences across both mobile and desktop.
13c13,19
< **Requires PHP:** 5.6  
---
> **Requires PHP:** 5.6
> 
> [![Build Status](https://github.com/ampproject/amp-wp/workflows/Build,%20test%20&%20measure/badge.svg)](https://github.com/ampproject/amp-wp/actions?query=branch%3Adevelop+workflow%3A%22Build%2C+test+%26+measure%22)
> [![Coverage Status](https://img.shields.io/codecov/c/github/ampproject/amp-wp/develop.svg)](https://codecov.io/gh/ampproject/amp-wp)
> [![Built with Grunt](https://gruntjs.com/cdn/builtwith.svg)](http://gruntjs.com)
> 
> ## Description
15c21
< [![Build Status](https://travis-ci.org/ampproject/amp-wp.svg?branch=develop)](https://travis-ci.org/ampproject/amp-wp) [![Coverage Status](https://img.shields.io/codecov/c/github/ampproject/amp-wp/develop.svg)](https://codecov.io/gh/ampproject/amp-wp) [![Built with Grunt](https://gruntjs.com/cdn/builtwith.svg)](http://gruntjs.com) 
---
> This official plugin from the AMP project enables AMP content publishing with WordPress in a way that is fully and seamlessly integrated with the standard mechanisms of the platform.
17c23
< ## Description ##
---
> [![Play video on YouTube](https://i1.ytimg.com/vi/s52JNMT59s8/hqdefault.jpg)](https://www.youtube.com/watch?v=s52JNMT59s8&list=PLXTOW_XMsIDRGRr5QDffrvND8Qh1RndFb)
19c25,27
< This official plugin from the AMP project enables AMP content publishing with WordPress in a way that is fully and seamlessly integrated with the standard mechanisms of the platform. The key features are the following:
---
> For more videos like this, check out the ongoing [AMP for WordPress video series](https://www.youtube.com/playlist?list=PLXTOW_XMsIDRGRr5QDffrvND8Qh1RndFb).
> 
> The plugin's key features include:
28c36,38
< ### AMP Plugin Audience: Everyone ###
---
> 
> ### AMP Plugin Audience: Everyone
> 
36c46,47
< ### Template Modes ###
---
> ### Template Modes
> 
47c58,59
< ### AMP Ecosystem ###
---
> ### AMP Ecosystem
> 
52c64,65
< ### AMP Development ###
---
> ### AMP Development
> 
55c68,69
< ### Getting Started ###
---
> ### Getting Started
> 
58c72
< If you are a developer, we encourage you to [follow along](https://github.com/ampproject/amp-wp) or [contribute](https://github.com/ampproject/amp-wp/blob/develop/contributing.md) to the development of this plugin on GitHub.
---
> If you are a developer, we encourage you to [follow along](https://github.com/ampproject/amp-wp) or [contribute](https://github.com/ampproject/amp-wp/wiki/Contributing) to the development of this plugin on GitHub.
64,65c78
< 
< ## Installation ##
---
> ## Installation
71c84
< ## Frequently Asked Questions ##
---
> ## Frequently Asked Questions
75c88
< ## Screenshots ##
---
> ## Screenshots
79c92
< ![New onboarding wizard to help you get started.](wp-assets/screenshot-1.png)
---
> ![New onboarding wizard to help you get started.](.wordpress-org/screenshot-1.png)
83c96
< ![Built for developers and non-technical content creators alike.](wp-assets/screenshot-2.png)
---
> ![Built for developers and non-technical content creators alike.](.wordpress-org/screenshot-2.png)
87c100
< ![Theme selection to enhance the Reader mode experience.](wp-assets/screenshot-3.png)
---
> ![Theme selection to enhance the Reader mode experience.](.wordpress-org/screenshot-3.png)
91c104
< ![Preview how your site looks across desktop and mobile before finalising changes.](wp-assets/screenshot-4.png)
---
> ![Preview how your site looks across desktop and mobile before finalising changes.](.wordpress-org/screenshot-4.png)
95c108
< ![Customize the design of AMP pages in the Customizer.](wp-assets/screenshot-5.png)
---
> ![Customize the design of AMP pages in the Customizer.](.wordpress-org/screenshot-5.png)
99c112
< ![Reopen the onboarding wizard, change individual options, or manage advanced settings.](wp-assets/screenshot-6.png)
---
> ![Reopen the onboarding wizard, change individual options, or manage advanced settings.](.wordpress-org/screenshot-6.png)
101c114
< ## Changelog ##
---
> ## Changelog
105c118
< ## Upgrade Notice ##
---
> ## Upgrade Notice
108d120
< 

@westonruter westonruter added this to the v2.1 milestone Jan 26, 2021
@github-actions
Copy link
Contributor

github-actions bot commented Jan 26, 2021

Plugin builds for 6222a32 are ready 🛎️!

Copy link
Member

@amedina amedina left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ship it.

bin/transform-readme.php Outdated Show resolved Hide resolved
bin/transform-readme.php Outdated Show resolved Hide resolved
-1,
$replace_count
);
if ( 0 === $replace_count ) {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This condition will never be true as $replace_count will always have a value > 0 after the screenshot transformations above, and preg_replace_callback() will increase that previous value by the number of replacements done here. So, the condition should either be $replace_count === $replace_count, or use an unset variable.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't seem to be the case: https://3v4l.org/0CGoT

<?php
$str = 'abcba';

$str = preg_replace( '/b/', 'a', $str, -1, $replace_count );
var_dump( $replace_count );

$str = preg_replace( '/c/', 'a', $str, -1, $replace_count );
var_dump( $replace_count );

var_dump( $str );

The result is:

int(2)
int(1)
string(5) "aaaaa"

In other words, $replace_count is reset with each preg_replace_callback(). It doesn't increment on top of an existing variable. If it did, then the int(3) would be here instead of int(1).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea I've been terribly mistaken here. I was operating against changes I made locally 🤦. This is all good.

Co-authored-by: Pierre Gordon <[email protected]>
@westonruter
Copy link
Member Author

QA Passed

No readme.txt is in the repo now, and comparing the readme.txt in the 2.0 branch with what is generated as part of a build shows that it is faithfully being generated:

11c11
< The Official AMP Plugin, supported by the AMP team. Formerly Accelerated Mobile Pages, AMP enables great experiences across both mobile and desktop.
---
> The official AMP Plugin, supported by the AMP team. Formerly Accelerated Mobile Pages, AMP enables great experiences across both mobile and desktop.
15c15,21
< This official plugin from the AMP project enables AMP content publishing with WordPress in a way that is fully and seamlessly integrated with the standard mechanisms of the platform. The key features are the following:
---
> This official plugin from the AMP project enables AMP content publishing with WordPress in a way that is fully and seamlessly integrated with the standard mechanisms of the platform.
> 
> https://www.youtube.com/watch?v=s52JNMT59s8&list=PLXTOW_XMsIDRGRr5QDffrvND8Qh1RndFb
> 
> For more videos like this, check out the ongoing [AMP for WordPress video series](https://www.youtube.com/playlist?list=PLXTOW_XMsIDRGRr5QDffrvND8Qh1RndFb).
> 
> The plugin's key features include:
60c66
< If you are a developer, we encourage you to [follow along](https://github.com/ampproject/amp-wp) or [contribute](https://github.com/ampproject/amp-wp/blob/develop/contributing.md) to the development of this plugin on GitHub.
---
> If you are a developer, we encourage you to [follow along](https://github.com/ampproject/amp-wp) or [contribute](https://github.com/ampproject/amp-wp/wiki/Contributing) to the development of this plugin on GitHub.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants