Pkp-lib: Unify plugin READMEs and Plugin Gallery documentation

[asmecher]

Currently many plugins have READMEs (textual or Markdown) in their repos. The plugin gallery's XML also has a spot for inline self-documentation. It would be much better if both could rely on documentation built into the repository, to a) reduce the amount of duplication, b) give the plugin maintainer more control over the documentation, and c) make it less of a pain to maintain the plugin gallery.

[asmecher]

(Ping @amandastevens and @AhemNason)

[AhemNason]

hi, yes please.

[asmecher]

So this is easy to introduce:

diff --git a/classes/plugins/PluginGalleryDAO.inc.php b/classes/plugins/PluginGalleryDAO.inc.php
index f45a678..83c80b8 100644
--- a/classes/plugins/PluginGalleryDAO.inc.php
+++ b/classes/plugins/PluginGalleryDAO.inc.php
@@ -89,7 +89,12 @@ class PluginGalleryDAO extends DAO {
                    $plugin->setHomepage($n->nodeValue);
                    break;
                case 'description':
-                   $plugin->setDescription($n->nodeValue, $n->getAttribute('locale'));
+                   if ($href = $n->getAttribute('href')) {
+                       $parser = new \Michelf\Markdown;
+                       $plugin->setDescription($parser->transform(file_get_contents($href)), $n->getAttribute('locale'));
+                   } else {
+                       $plugin->setDescription($n->nodeValue, $n->getAttribute('locale'));
+                   }
                    break;
                case 'installation':
                    $plugin->setInstallationInstructions($n->nodeValue, $n->getAttribute('locale'));

However, there are some structural considerations before this won't look awful:

• Repository READMEs contain contact and credit information, which the Plugin Gallery already contains.
• Repository READMEs contain installation instructions, which might be irrelevant or, worse, different than the Plugin Gallery requires.
• There's no support in github (yet) for READMEs in different languages.

Here's the convention I propose:

• Have a bare-bones repository README.md that has the plugin name, credit, license and contact information. It should then contain links to the _actual_ documentation, for each language available.
• Have a docs directory containing the real meat of the docs, with ideally files there for each locale: README-en_US.md, etc.

(This is just a convention, and it would be linked from the Plugin Gallery XML using a new href attribute to the description element, so we could actually put this anywhere we want.)

That way viewers on Github.com will see the wrapper README, which will be relevant to them. They can click through to get the user documentation.

Viewers reading the documentation from the Plugin Gallery will see the relevant subset of documentation, in the right language.

Sound good?

[mtub]

Sound good?

I think it does. If we can enforce/recommend a template for the README files, I'd prefer

/docs/en_US/README.md
/docs/de_DE/README.md

over

/docs/README-en_US.md
/dovs/README-de_DE.md

It's more in sync with the organisation of locale files, it's easier to parse (by a human), and it allows to include other files (images etc.) in the localised documentation.

[isgrim]

Yes please, I thought about how to include documentation on ORCID plugin configuration via the config.inc.php file and wanted to put it in the README.md.

[NateWr]

Sounds good. So with this method the main README.md will not contain any actual instructions? And so if a plugin needs to provide distinct developer vs. user documentation, they'd just roll their own structure and create their own navigation path through it?

One potential hiccup here is security. We use the md5 hash of the release package to prevent against abuse from a hostile takeover of a github account. We could use a similar technique for the readme file, but that raises a couple questions.

1. Will we md5 hash every readme file involved? Or do we only render the main readme and for other parts of the docs the user will go to GitHub or anywhere they are linked to, I suppose? (Or are we planning to show the docs from the installed plugin files?)

2. As a plugin maintainer, I'm likely to update the README between releases. If I have to update the md5 hash in my plugin's entry, that's likely to be forgotten and we'll end up with a lot of documentation going "missing" in the UI.

3. How can we avoid confusion with the app versioning and the docs. If I'm on 3.1, the app will only show and install versions of a plugin that are compatible with 3.1. How can we indicate that the documentation is out-of-date?

Also, I'll just drop this in here as an alternate approach to accessing documentation in the app: https://github.com/pkp/pkp-lib/issues/3456. It's a proposal (with a PR) to allow plugins to add their own pages to the in-app help panel. I've dropped the ball on that PR but if I recall it was pretty close to ready to go.

[asmecher]

@NateWr, +1 to making this play well with the in-app help. I was thinking along those lines when I drafted up the basic proposal in the comment above (not even a PR yet as it isn't ready) -- it uses the same Markdown transformation as the help system.

1 and 2: On md5 hashing and trust: I was thinking that the onus falls on us as the plugin gallery administrators to make sure we're using "invariant" links, i.e. URLs into github repos that include hashes per the tagged version. (Even tags can be moved, so we can't rely on those.) (I suppose we could add md5 hashes for the documentation alongside the hrefs, but I'm ambivalent about that, especially insofar as we would only be hashing the linked Markdown document, and not anything attached to it.)

The downside to referencing a permalink by commit hash is that changes to the documentation will strictly require an update to the plugin gallery, but on the plus side, that's not tied strictly to the release. We'd be free to update the documentation link, or update the plugin code, or both, independently.

3: I'd like best practice to be that the documentation and release updates get done at the same time. Hrm, I think I follow your point here: this suggests that the release documentation HREFs should be attached to the release element, rather than the plugin element, so they can be version-specific. We can introduce that for future versions and maintain but deprecate the old approach, if that seems sensible.

[asmecher]

(@ajnyga, pinging you in case you're interested -- we're talking about new conventions for plugin self-documentation.)

[ajnyga]

all the above looks good. In general it would be nice to have a clear template you could use to create readme files.

This is not connected to readme files, but what is lacking I think is a way to tell OJS/OMP what versions the current plugin version is supporting. The best place would probably be the version.xml file. It could allow entries like <support>OJS.3.1.2.0</support> and OJS/OMP then could use those strings to show that a certain plugin is out of date. Or maybe you are already handling this from some other place?

[asmecher]

a way to tell OJS/OMP what versions the current plugin version is supporting

Agreed! Currently that information is available in a "trustworthy" form in the plugin gallery, but plugins themselves can't specify it, nor is there any information in the plugin version descriptor whether the plugin is compatible with only one or several apps.

[asmecher]

After some conversation with @NateWr and @ctgraham we're starting to come to a landing on some technical details:

• The plugin gallery XML may be best kept in a Git repository in the future, in order to facilitate user contributions and maintenance via pull requests. This may mitigate the need for an additional descriptor file added to each plugin's repository and compilation scheduled task on the PKP website to bring it all together.
• It may be possible to leverage plugin-based automated testing to help manage compatibility promises. I don't foresee this being an automatic compatibility indicator, since poor coverage of a plugin's tests would make it pretty much meaningless, but it has potential.
• We would like to reduce breaking changes in software builds that affect plugins, but foresee some growing pains there. Compatibility promises made by plugins can be made more flexible (i.e. regexp matches or something rather than explicit listings), but we may need to start rolling this out carefully/gradually.
• We're fielding a lot of support forum requests for help from users who downloaded and attempted to install the master branch code in their stable OJS installs. Should we add compatibility promises to the plugin's version.xml as well?

[NateWr]

On the issue of installing from master and getting errors. When we have
compatibility in the plugins.xml, we could use this during plugin enable,
to check if there is no compatibility and block enabling when it's not met.

On Tue, 22 Oct 2019, 19:24 Alec Smecher, [e-mail] wrote:

After some conversation with @NateWr https://github.com/NateWr and
@ctgraham https://github.com/ctgraham we're starting to come to a
landing on some technical details:

• The plugin gallery XML may be best kept in a Git repository in the
  future, in order to facilitate user contributions and maintenance via pull
  requests. This may mitigate the need for an additional descriptor file
  added to each plugin's repository and compilation scheduled task on the PKP
  website to bring it all together.
• It may be possible to leverage plugin-based automated testing to
  help manage compatibility promises. I don't foresee this being an
  automatic compatibility indicator, since poor coverage of a plugin's
  tests would make it pretty much meaningless, but it has potential.
• We would like to reduce breaking changes in software builds that
  affect plugins, but foresee some growing pains there. Compatibility
  promises made by plugins can be made more flexible (i.e. regexp matches or
  something rather than explicit listings), but we may need to start rolling
  this out carefully/gradually.
• We're fielding a lot of support forum requests for help from users
  who downloaded and attempted to install the master branch code in
  their stable OJS installs. Should we add compatibility promises to the
  plugin's version.xml as well?

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
https://github.com/pkp/pkp-lib/issues/4598?email_source=notifications&email_token=AARTERL5AWF2WLORMQPKBS3QP5APRA5CNFSM4G53NRG2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEB6XDYQ#issuecomment-545092066,
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AARTERKBIEGLSIZQP3SYSU3QP5APRANCNFSM4G53NRGQ
.

[ctgraham]

You know I am in favor of putting the burden on the shoulders of the developers to describe their compatibility expectations within the plugin, even at the expense of re-releasing unchanged code or patching because of a breaking upstream change.

The issue of mixing master code with stable installs gets me thinking though... this presumably happens because the plugin developers are not formalizing releases, are not tagging releases with user-facing version information, or the users are not finding/reading this. Which case (cases?) do you think is driving this?

N.b.: I'm a big fan of Drupal's plugin versioning scheme, where core compatibility is baked into the version.

[asmecher]

Which case (cases?) do you think is driving this?

I think it's a few things:

• Users who don't have tar properly configured to permit the plugin gallery to work
• Users who haven't set permissions in their install such that OJS can install plugins into its codebase
• Users who aren't logged in as Administrator, thus don't see Install buttons, and and may not know how the Plugin Gallery works

I think some users who couldn't figure out the Plugin Gallery, thus moved on to the .tar.gz upload, will simply move on from there, if blocked, to manually adding code to the repo. There's only so much we can do :)

[ctgraham]

But my question is: what is driving them to the master branch? Is it the link from within the plugin gallery? What prevents them from finding an appropriately tagged release?

[asmecher]

What prevents them from finding an appropriately tagged release?

I think a lot of users are seeing the big "Download" button beside the repo homepage and simply hitting that. I don't think they checked the "Releases" area at all. I kind of wish we could disable the Download button entirely to avoid this complication but I don't think it's possible.

[asmecher]

@NateWr:

On the issue of installing from master and getting errors. When we have compatibility in the plugins.xml, we could use this during plugin enable, to check if there is no compatibility and block enabling when it's not met.

It's an option, but I like the conceptual clarity of keeping the .tar.gz uploader completely separate from the Plugin Gallery. Currently the .tar.gz uploader can operate completely separately from any contact between OJS and the PKP website, and adding a compatibility check to the .tar.gz uploader would necessitate a download of the plugin gallery's plugin listing.

The other option would be to add compatibility information to the plugin's version.xml, but we'd be maintaining the compatibility information separately in two places that way, and it would dilute the elegance of using a github repo to have PKP vet and include plugin metadata.

[ctgraham]

Maybe best practice for a plugin README should be to include a "Downloads" section. Or, if the source of discovery is the Plugin Gallery, maybe we should provide an explicit "download" link.

[NateWr]

adding a compatibility check to the .tar.gz uploader

I was thinking something on the CLI side. So that when an upgrade is initiated, it first checks the plugin compatibility list against the currently installed plugins and identifies those that are not compatible.

what is driving them to the master branch?

I think it's a mix of the things you've mentioned: the design of the gallery, the prominence of the github link, the lack of additional information. I think we can disincentivise this through improvements to the UX of the gallery.

One idea would be to have the .tar.gz uploader behind a "developer mode" toggle or something? So someone has to opt into uploading plugins that aren't "approved", and when they do so we can provide them with a helpful warning message, like "the plugins may not work. check compatibility. don't blame us."

[asmecher]

The plugin gallery is already overdue for some UI/UX work. In terms of users who don't know how to meet its technical requirements, we'll always be hobbled by the file permission requirements, but we might also be able to make some progress on the tar requirement by using a 3rd-party polyfill (see a similar mention at https://github.com/pkp/pkp-lib/pull/5211#discussion_r338183355).

I like the idea of adding a stern warning to the .tar.gz uploader -- and generally disincentivizing it --
rather than working too hard to build in additional checks.

[NateWr]

Just adding this one while it's in my head: in addition to the developer toggle/warning, can we also check if we have sufficient file permissions and throw a warning message into the plugin gallery if we don't?

[ctgraham]

Checking the file permissions will supersede https://github.com/pkp/pkp-lib/issues/869 and https://github.com/pkp/ojs/pull/663 at this point.

I like the idea of a warning (but I wouldn't hide it or call it a "developer" function), and I don't mind the duplication of the compatibility info within the plugin and within the proposed git repo. An additional point of duplication will/should be the release itself, either by name or description.