Release checklist for tagging version 1.3.2.4

This checklist takes about four hours to run fully.

Team Prep Work

Before merging

The owner of the release needs to complete the following steps BEFORE merging the version-bump branch and tagging the release:

Release process

bump version number
tag and push to github
release.sh
publish release in GitHub: https://github.com/INN/pym-shortcode/releases/tag/v1.3.2.4
close milestone

After release is published

update plugins on our sites (inndev? ccs?)
publish update announcement blog post
tweet announcement and schedule 2-5 for the next 7 days (via TweetDeck, HootSuite, or similar) with simple download prompt or tweets detailing new features, like "Newsroom Staff Pages should be clean and useful. We think so too. See Largo 0.X's new...." Make sure these tweets get cross-tweeted between INN accounts.
add to Nerd Alert for following week
create the release ticket for the next milestone from this one
prune stale and merged branches
notify maintainers of related plugins: News Project, WP AMP,

Override pym_id to resize after following links in iframe?

I'm so glad you've created this plugin! 😁

I have some clients who want to use it to embed event registration and membership forms from another application. To work well, the iframe needs to resize at each screen of the process.

The Pym docs show how to do this (jump to Example: Resizing after following links in the iframe), and I've tried to follow the instructions. I am using a local WordPress test site and the following code on each page of my silly little child site:

    <script src="https://pym.nprapps.org/pym.v1.min.js"></script>
    <script>
      var pymChild = new pym.Child({ id: '[UNIQUE ID FOR EACH PAGE]' })
    </script>

(I've also tried replacing id with pym_id - no effect that I can see.)

The iframe loads beautifully for the first page, but when I click through to other pages inside the iframe, the iframe height doesn't change. The ID of the parent div is always pym_0, where I would expect it to be replaced with my specific unique ID from the child page.

Any tips? I don't mind forking the plugin and making my own changes, but if there's a way I can make it work with the existing code, that would be best for my clients.

Thanks!

Dealing with persistence?

Sometimes you need a different embed code, like the Seamus ones:

<div id="responsive-embed-budget_by_dollar"></div>
<script type=text/javascript>
    (function(jQuery) {
        if (typeof jQuery !== 'undefined' && typeof jQuery.getScript === 'function') {
            // add randomness to id to support for multiple graphic instances in one story
            var el = document.getElementById("responsive-embed-budget_by_dollar");
            el.id = el.id + "-" + Math.random().toString(36).substr(2,5);
            jQuery.getScript("//pym.nprapps.org/pym.v1.min.js").done(function () {
                jQuery(function () { // Wait for page load
                    var pymParent = new pym.Parent(
                        el.id,
                        'http://f.benlk.com/graphics/budget_by_dollar/child.html',
                        {}
                    );

                    jQuery.getScript("//carebot.nprapps.org/carebot-tracker.v0.min.js").done(function () {
                        var tracker = new CarebotTracker.VisibilityTracker(el.id, function(result) {
                            // Ignore Carebot events to empty embeds, keeps listening after unloading the page
                            if (pymParent.el.getElementsByTagName('iframe').length !== 0) {
                                pymParent.sendMessage('on-screen', result.bucket);
                            }
                        });
                        // Check if there is already an scroll tracker somewhere on the page
                        if (!document.querySelector("[data-carebot-scroll]")) {
                            pymParent.el.setAttribute("data-carebot-scroll", "");
                            var scrollTracker = new CarebotTracker.ScrollTracker('storytext', function(percent, seconds) {
                                // Ignore Carebot events to empty embeds, keeps listening after unloading the page
                                if (pymParent.el.getElementsByTagName('iframe').length !== 0) {
                                    pymParent.sendMessage('scroll-depth', JSON.stringify({percent: percent,seconds: seconds}));
                                }
                            });
                        }
                    });

                });
            });
        } else {
            console.error('could not load graphic: jQuery is not on the page.');
        }
    })(window.jQuery);
</script>

Do we want this plugin to handle that? Do we want to make a different plugin, supporting the same shortcode, that does a different type of initialization?

Provide a sample shortcode to allow testing

We got a support ticket from a user who doesn't have access to the list of active plugins, who wanted to know whether it was active.

assemble a demo shortcode
add the demo shortcode to the plugin's docs or FAQ in the readme, under a heading something like "I don't have access to my site's plugins page. How can I tell if this shortcode is active?" with a response along the lines of "create a draft post with this shortcode and preview it; you should see something like this:"

Test against Gutenberg 4.0 and WP 5.0

https://github.com/WordPress/gutenberg/releases/tag/v4.0.0-rc.1

docs: HTTPS concerns

How do you serve pym.js if the embedded page's domain has an SSL cert (and can/will be served over HTTPS) but the parent page's domain does not have an SSL certificate?
- use a HTTPS-providing javascript CDN, like https://cdnjs.cloudflare.com/ajax/libs/pym/0.4.5/pym.min.js for the embedded page's <script src=""
How do you detect HTTPS problems?
- embed not sizing correctly
- open embed in new tab

Tag 1.3.2.1

all issues in 1.3.2.1 milestone
update description in readme.txt and plugin description comment. https://github.com/INN/pym-shortcode/blob/a439690dafcd97e1352ba554393926b9a0b68740/pym-shortcode.php#L5
testing in accordance with todo list and updating the docs/testing doc: 2h max
update version number
update release.sh from INN/docs copy if applicable
update repository description on Github; presently it's:

A plugin adding a [pym src=""] shortcode to simplify the process of using http://blog.apps.npr.org/pym.js/
copy release notes from https://github.com/INN/pym-shortcode/releases/tag/v1.3.2.1-rc1 into the release notes for 1.3.2.1, or just replace the 1.3.2.1-rc1 section of the changelog with 1.3.2.1
shoutout to the testers

Gutenberg Block failing for me on Wordpress.com

Without warning, this plugin stopped working on WP.com today. The Pym JS library doesn't load. Support has asked me to contact yall (what up INN friends!!). If you have any ideas, I'd love to know. I don't see any updates to the plugin recently, and it had been working for weeks up until now.

I did have a notion that Gutenberg might be a culprit, but the same problem crops up in the classic editor. We have a business account, so we can use unfiltered html in the advanced editor, and that works fine.

php error with latest version?

All my shortcodes are broken now that I'm unable to activate this plugin -- Here's the message I get:

Parse error: syntax error, unexpected T_STRING, expecting T_CONSTANT_ENCAPSED_STRING or '(' in /home/mattstiles/webapps/heyelise/wp-content/plugins/pym-shortcode/inc/shortcode.php on line 8

Halp?

This plugin needs a logo for its wp.org listing.

Nothing fancy, but still, needs a logo.

https://wordpress.org/plugins/pym-shortcode/

https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/#plugin-icons

Are we on the latest Pym?

https://github.com/nprapps/pym.js/blob/master/dist/pym.js might be different, based on #11 .

"Why would I want to change the pym source" section of docs needs example link

#6

Editor JS not enqueued in WordPress 5.0-beta versions

As far as I can tell, the Pym.js Embeds block does not work in 5.0-beta3, 5.0-beta2, or 5.0-beta1.

This is part of #54.

Add `pym_id` attribute to the shortcode to allow custom ID names

This grows out of #20:

We should probably make a new pym_id parameter on the shortcode that allows end users to configure the ID of the generated embed on the page.

https://github.com/INN/pym-shortcode/blob/master/pym-shortcode.php#L54 would change to something like:

( isset( $atts['pym_id'] ) ) ? $atts['pym_id'] : "pym_$pym_id" ,

Content does not appear on page load, but does on window resize

I'm using pym for a quiz that gets it's content from a Google Sheet. When I load the page, nothing appears. In the inspector, I can see pym is showing up, but the height is 0. If I resize the window in any way, it starts working and the quiz appears.

Here's the page I'm referring to: http://www.sciencefriday.com/segments/quiz/
And the page pym is drawing from: http://scifri.github.io/newsquiz/index.html

I'm guessing this bug could be coming from one of the javascript files this quiz is using, which include jquery.js, tabletop.js, and script.js. Not sure if there's a documented problem with using pym with one of these.

The quiz code is from the Mother Jones open source quiz tool: https://github.com/motherjones/newsquiz

Add block transform for converting a Shortcode block containing a Pym shortcode into a Pym Block

From #34:

Add support for converting the shortcode block containing a Pym iframe into a Pym Block, once WordPress/gutenberg#8569 has been resolved

Review `http:` strings in plugin and update to `https:` where possible

https://github.com/INN/pym-shortcode/blob/ee341bd307754ea1025a98ddcfe235165c04aca4/pym-shortcode.php#L8

This was reported by @claudiulodro in Automattic/newspack-plugin#276 (comment)

Allow passing a class name to target DIV

We have a couple size-based class names in our site styles, and it's been handy to use those to size embeds. When we're just writing HTML, it's easy to do something like:

<div class="interactive medium" data-pym-src="..."></div>

Would be great to be able to:

[pym src="..." class="interactive medium"]

Test in Reader Mode in various browsers

https://medium.com/@mandy.michael/building-websites-for-safari-reader-mode-and-other-reading-apps-1562913c86c9

how does the embed appear?
what sort of fallback content can/should we provide?

docs: directions to instructions on building Pym-compatible embeds

This is probably just linking to NPR's docs, but there are likely other resources out there that we might want to review.

Write PHP tests

fab wp.tests_setup:pym
review code for things that will need to be tested especially
create list of high-priority tests and low-priority tests
- assume that WordPress settings functions work
Write tests for pym_shortcode( $atts, $context, $tag )
- alternate src is included if set
- otherwise, src is the path in the plugins directory plugins_url( '/js/pym.js',$whatever_the_pym_plugin_file_path_is )
- page contains markup corresponding to placed source code
- a post with n shortcodes contains each of echo '<div id="pym_' . $n . '"></div>';

React is dropping className for class

Keep an eye on facebook/react#13525 and update this plugin when Gutenberg switches from className to class.

add a deprecated block method to support upgrading from className to class
are changes in the shortcode necessary? Do those too.
changelog docs

Add block transform for converting a Pym block into a generic embed

From #34:

create a https://wordpress.org/gutenberg/handbook/block-api/#transforms-optional transform method that converts the Pym block into a generic embed block

Remove Pull Request Template from this repo so it's covered by INN's org-wide PR template

https://github.com/INN/pym-shortcode/blob/master/.github/pull_request_template.md

remove it

Release checklist for tagging version 1.3.2.3

Drawing from Largo's 0.7.0 release checklist issue WPBuddy/largo#1798, the SCAMP 0.3 tag checklist INN/doubleclick-for-wp#83, Automattic/republication-tracker-tool#63, and other issues:

Team Prep Work

Before merging

The owner of the release needs to complete the following steps BEFORE merging the version-bump branch and tagging the release:

Release process

bump version number
tag and push to github
release.sh
publish release in GitHub -> https://github.com/INN/pym-shortcode/releases/tag/v1.3.2.3
close milestone

After release is published

update plugins on our sites (inndev? ccs?)
publish update announcement blog post
tweet announcement and schedule 2-5 for the next 7 days (via TweetDeck, HootSuite, or similar) with simple download prompt or tweets detailing new features, like "Newsroom Staff Pages should be clean and useful. We think so too. See Largo 0.X's new...." Make sure these tweets get cross-tweeted between INN accounts.
add to Nerd Alert for following week
create the release ticket for the next milestone from this one -> #71
prune stale and merged branches
notify maintainers of related plugins: News Project, WP AMP

rename text domain

When did I introduce the text domain? Can we rename it from pym-shortcode to pym-embeds without affecting stuff?

I mean, this plugin doesn't ship with translation files at the moment, so how hard could it be?

Add CONTRIBUTING.md

This should copy INN Labs' boilerplate contributing.md, possibly with a github issue template. https://blog.github.com/2016-02-17-issue-and-pull-request-templates/

Because shortcodes and blocks are processed at different times, a shortcode can be output without necessary dependencies on the page

Originally reported in #34, the ticket for adding Gutenberg support to the plugin.

With the following post_content:

<!-- wp:shortcode -->
[pym src="https://f.benlk.com/graphics/heartbeat-abortion-bills/child.html"]
<!-- /wp:shortcode -->

<!-- wp:paragraph -->
<p>the preceding is a shortcode block.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>The following is the Pym Embed:</p>
<!-- /wp:paragraph -->

<!-- wp:pym-shortcode/pym {"src":"http://blog.apps.npr.org/pym.js/examples/table/child.html","align":"full"} /-->

The following output:

<div id="pym_1" class="pym  "></div>
<script>var pym_1 = new pym.Parent('pym_1', 'https://f.benlk.com/graphics/heartbeat-abortion-bills/child.html', {})</script>
<p>the preceding is a shortcode block.</p>
<p>The following is the Pym Embed:</p>
<div id="pym_0" class="pym alignfull "></div>
<script src="http://pym-shortcode.test/wp-content/plugins/pym-shortcode/js/pym.v1.min.js"></script><script>var pym_0 = new pym.Parent('pym_0', 'http://blog.apps.npr.org/pym.js/examples/table/child.html', {})</script>

After dumping the filters hooked on 'the_content' with global $wp_filter; var_dump( $wp_filter['the_content'], true );, I found that the block rendering filter do_blocks runs before the shortcode renderer do_shortcode.

Thus, in a post with one block and one shortcode, the first block gets the id pym_0 and the first shortcode gets the id pym_1.

Because the current behavior of the function pym_shortcode() — which is used for the shortcode and the block output — is to output the Pym.js-loading tag <script src="http://pym-shortcode.test/wp-content/plugins/pym-shortcode/js/pym.v1.min.js"></script> only during the first call, for pym_0, the later call to pym_shortcode() earlier in the post_content doesn't output the script tag, which means that pym_1's new pym.Parent call doesn't work, because pym is not yet defined.

typo in docs: nwesroom

or your nwesroom's CDN

git-grep for nwesroom, fix the typos.

Filter allowing theme/plugin devs to put classes on pym shortcode output

For example, if it was desired that all pym embed parent divs should have the class pym_parent:

/**
 * add 'pym_parent' to the classes on the pym field array
 * @param Array $classes
 * @return Array
 */
function my_pym_class_filter( $classes ) {
    $classes[] = 'pym_parent';
    return $classes;
}
add_filter( 'pym_element_classes', 'my_pym_class_filter' );

Update support.inn.org docs

The documentation at https://support.inn.org/article/100-pym-shortcode needs to be updated in the following ways:

"There are no plugin settings" is false since version 1.3.2.1 in 2018, when we added a settings page. We can probably strike the words "There are no plugin settings, but" and start the sentence with "There are some...."
This page should mention Gutenberg compatibility before the shortcode.
Include a link to https://blog.apps.npr.org/pym.js/ and credit NPR somewhere on the page.

Discovered during #68

Provide a setting to allow site admins to opt into using the CDN version of Pym

Wordpress' plugin guidelines require that we include pym.js locally, and that that version be used by default. This is because WordPress forbids loading executable code from CDNs: https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/#8-plugins-may-not-send-executable-code-via-third-party-systems

However, if we created a setting that allowed people to opt into using the NPR-CDN-provided version of Pym.js, and that setting page included sufficient warnings and explanations, we would be able to provide the option of enabling the CDN version to people who are interested in using it without having to set the pymsrc attribute on every single shortcode.

AMP support?

Fallback cases where Pym.js fails to load in the parent

For shortcodes:

allow the shortcode to be used as a [pym src=""]foo[/pym] that passes the contents to $content to be used as the innards of the placeholder div: <div id="pym_1" class="pym ">foo</div>

For blocks:

for blocks, the placeholder is a link to the embed

Specific to AMP

For whatever WordPress AMP plugins we want to support:

provide a transformation that ensures the appropriate Pym JS tags are output as part of the AMP content
Investigate whether Pym can use amp-iframe as a pymParent: nprapps/pym.js#182

Use Gutenberg's native `anchor` support for setting the pym parent element ID

We didn't do this in the initial implementation of Gutenberg blocks in #34 because, at the time, it appeared as if there was no way to use Gutenberg's anchor property with a block that was dynamically rendered.

For more history, see the following comments:

#34 (comment)
WordPress/gutenberg#6356 (comment)
https://github.com/WordPress/gutenberg/pull/8154/files, the current version of which is https://wordpress.org/gutenberg/handbook/block-api/#supports-optional

Elements of this ticket:

remove the shim introduced in #34
add a supports declaration for anchor
add the anchor output to the pym_shortcode function.

Add internationalization/i18n for text strings in the block

This issue is waiting on answers to the questions in WordPress/gutenberg#9517 .

Once we have an answer,

re-add the text domain removed in the commit f73f965
create a .pot and enqueue it as necessary

Does the `pymoptions=""` attribute actually support backslashes?

We have this example in readme.txt:

[pym src="child.html" pymoptions=" xdomain: '\\*\.npr\.org' "]

Which is supposed to output: (with supporting code)

pym.Parent('pym_0', 'child.html', { xdomain: '*\.npr\.org' });

But what it actually puts on the page is this:

pym.Parent('pym_0', 'child.html', { xdomain: '\*.npr.org' })

Inside, the $pymoptions variable is this:

error_log( var_export( $pymoptions, true ) );
' xdomain: \'\\*.npr.org\' '

If we esc_js() that, it's this, still not what we're looking for:

' xdomain: \\\'*.npr.org\\\' '

In conclusion: slashes aren't being output correctly.

How will we deal with a breaking change in Pym?

Eventually, Pym.js may publish a backwards-incompatible API change, at which point we'll need to figure out how to handle existing graphics embedded with a version of this shortcode that does not specify to use the older version of pym. (https://github.com/nprapps/pym.js/tree/master#versioning)

How should we handle that breaking change?

Add settings page

This would cover several options:

provide URL to the plugin's site-hosted version of Pym.js, for use when building embeds
#31: option to enable CDN version of pym.js
#8: settings to whitelist certain pymsrc options, to prevent contributors/authors from embedding arbitrary JS on the page
#19: option to change embed script source for persistence reasons

The full set of features needed:

Instead of putting script tags in the article for the Pym script source, enqueue!

https://github.com/INN/pym-shortcode/blob/8047878a94ed8740fdc6cd3feb334168d07263dc/pym-shortcode.php#L61-L68

This should instead:

If the pymsrc attribute is set, enqueue that script in the footer.
If pymsrc is not set, enqueue the default script. (See also #31)

The `pymsrc` option allows users to load arbitrary javascript on the page.

The content of the pymsrc script is output directly to the page: https://github.com/INN/pym-shortcode/blob/26bbef9e561651da110e6dc77d590bc362736fa5/pym-shortcode.php#L31

    if ( $pym_id == 0 || $atts['pymscr'] ) {
        echo sprintf(
            '<script src="%s"></script>',
            $pymsrc
        );
    }

We should check to make sure that this is at least a URL.

We may want to consider implementing a whitelist in the future, for security reasons.

Text domain corrections

https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/ says regarding declaring a text domain:

After WordPress 4.6 came out, the Text Domain header is no longer required if it’s the same as the plugin slug. It’s now the default value.

However, this plugin does not declare a text domain, and uses multiple text domains.

In the start and end of this quoted section, we use 'pym_shortcode'

https://github.com/INN/pym-shortcode/blob/7ad2ca8d694e030944d37123622e4820f19d4f17/inc/class-pymsrc-output.php#L123-L138

Elsewhere in the plugin, we use 'pym-embeds':

https://github.com/INN/pym-shortcode/blob/b62b061ba3a0438878b110b18f0c1b1b59faf76d/inc/settings-page.php#L59-L60

https://github.com/INN/pym-shortcode/blob/a8666141cbb12876e36de77fc96578e680e3ef00/inc/info-page.php#L20-L21

Neither of those matches the .org plugin slug of pym-shortcode, which is what is most likely that this plugin has been installed under

pick a text domain
update all text-domain strings to that domain
declare the text domain explicitly
add note in PR template about new translatable strings matching the project one

Problems with height of the iframe: only displays top part

I am testing the plugin. Everything works fine except the height of the iframe, it only shows half of the top part of the iframe:
http://bilbaodatalab.wikitoki.org/2017/01/10/workflow-de-un-proyecto-de-datos/#datavis

I am trying to embed this responsive scatter plot in a post and this is how it looks:

docs: info about Pym.js

better link to NPR
situations where you would want to use Pym: why use Pym?
situations where you would not want to use Pym, or do not need to use Pym

Raise docs to WordPress.org compatibility standard

https://developer.wordpress.org/plugins/wordpress-org/

contributors: inn_nerds becomes innlabs

update contributors lines in readme.txt and pym-shortcode.php to be innlabs, not inn_nerds
transfer plugin ownership to innlabs

docs: installation of plugin

Gutenberg block editor support

Rename plugin

https://developer.wordpress.org/plugins/wordpress-org/plugin-developer-faq/#can-i-change-my-plugins-name-after-its-approved

Can I change my plugin’s name after it’s approved? #Can I change my plugin’s name after it’s approved?
Yes and no. You can change the display name, but the slug — that part of the plugin URL that is yours — cannot be changed once a plugin is approved. That’s why we warn you, multiple times, upon submission.

To change the display name, edit your main plugin file and change the value of “Plugin Name:” to the new name. You may also want to edit your header in your readme.txt

Right now, the plugin is called "Pym Shortcode".

When we add Gutenberg support in #34, that title will be an incomplete description of the plugin. What should we call it?

Test against WordPress 5.4 RC

Without AMP

Plugin settings:

Does the plugin settings page work? /wp-admin/options-general.php?page=pym-embed-settings
Does the plugin info page work? /wp-admin/tools.php?page=pym-embeds-info

Shortcode tests:

Gutenberg tests:

the block, when inserted, prompts users for a URL
the block's alignment, custom classes, custom ID, and other options are respected.
the block uses the default pymsrc URL if the pymsrc attribute is not set
on a site with Gutenberg not installed, the plugin functions
on a without Gutenberg installed, the plugin functions

With AMP

Plugin settings:

Does the plugin settings page work? /wp-admin/options-general.php?page=pym-embed-settings
Does the plugin info page work? /wp-admin/tools.php?page=pym-embeds-info

Shortcode tests:

Gutenberg tests:

the block, when inserted, prompts users for a URL
the block's alignment, custom classes, custom ID, and other options are respected.
the block uses the default pymsrc URL if the pymsrc attribute is not set
on a site with Gutenberg not installed, the plugin functions
on a without Gutenberg installed, the plugin functions

Make pym path configurable

Unfortunately, the version of pym that is bundled here is buggy in certain cases. Also, as changes get made, this means we would have to update this repository and update the wordpress site.
Making the pym path configurable would make it easier to keep up with changes without having to redeploy this plugin.

automattic / pym-shortcode Goto Github PK

pym-shortcode's Introduction

Pym.js Embeds

pym-shortcode's People

Contributors

Stargazers

Watchers

Forkers

pym-shortcode's Issues

Team Prep Work

Before merging

Release process

After release is published

Team Prep Work

Before merging

Release process

After release is published

Fallback cases where Pym.js fails to load in the parent

Specific to AMP

Without AMP

With AMP

Recommend Projects

Recommend Topics

Recommend Org