textpattern
proposed: Registering plugin tags
Proposed title and location of new page... "Register Textpattern plugin tags" Deferring location to @wion and @Bloke based on recent work.
Situation/Scenario for proposal
Textpattern 4.8.0 will break some existing plugins for administrators, beyond the usual minor release changes. Many plugins can be reactivated by registering the plugins tags, but this will be beyond many admin's reach without advice, especially given the widespread use of abandoned & hacked plugins that are still out there.
Proposal: a walkthrough, with examples, of how plugin code can be updated by the administrator where the original plugin author is not able to make the changes for an updated release.
Value
I predict the forum and social media channels will include administrators who haven't read the release notes, haven't taken a backup, and upgraded to 4.8.0, breaking the plugins and this affecting site functionality. We can sidestep a lot of support requests with a carefully-written technical document of how to fix plugins, perhaps with a link to the doc in HISTORY.txt if required.
Resources to consider for draft
Add information text and link
- https://forum.textpattern.com/viewtopic.php?pid=320759#p320759
- https://forum.textpattern.com/viewtopic.php?pid=320762#p320762
- https://forum.textpattern.com/viewtopic.php?pid=297784#p297784
Excellent idea. Plenty of resources in the forum about how to do it for a number of scenarios, as you found. We should cherry pick those and make a doc in the troubleshooting area, and link to it from the "extending Textpattern" or plugins area of the docs.
I've added the plugin dev index link to index2, which seems best positioned under the 'More' section of /build.
As for the proposed page, which is a good idea, I don't see it as a troubleshooting topic so much as just a specific kind of plugin topic. So if you draft such a page, drop in /development, and link to it from the /development index page doc, as presumably the other 11 pages in that directory are linked to (?), That's probably good enough.
- Location: /development/registering-plugin-tags
- h1 title: 'Registering plugin tags'
- Metadata: Use 'Textpattern' as you want in the metadata, but it doesn't need to be repetitive in the human-readable stuff.
Speaking of the /development directory. Would it not make more sense to treat the index file there as a contents list for all the dev docs in that directory? That might then make all those 11 (12) development docs more accessible under the main /development index link.
I realize this is not what we do in some cases with tag doc items (e.g. /tags/learning), but that's largely because of the constraints with improving the /tags branch in general. Still, I think we should make use of indexes as contents list rather than actual docs in most other cases.
I've merely tweaked a bunch of the docs within the /development directory for 4.8-ness. Not really thought beyond that and how they might be indexed. Making index.md a list is probably a good idea.
I don't mind where the proposed doc sits. I mentioned troubleshooting because, to me, if I've upgraded and some plugins stop working because of some changes made in core, my initial reaction wouldn't be to go to the /development area to find out why. I'm in trouble, I need to shoot it before my client gets mad!
But if you don't think it belongs in troubleshooting, that's cool. I'm not exactly sure what we consider 'troubleshooting' if it's not for finding out why something isn't behaving as expected, or as it was before something changed. Guidance appreciated so I can grok the distinction and we don't end up in 574-FAQ-documents land again.
Your intuition on placement is probably more common to people working with plugins, which I don't do. Let's do as you suggest.
I'm in the same boat as @wion – I don't do plugins, so I'll defer any decision on where it lives/what it looks like/etc. Grateful for your attention and work on this, thanks both.
NTS: update https://github.com/textpattern/textpattern/blob/dev/HISTORY.txt with article link if appropriate. Will probably need a .com shortcut/pretty URL.
Having just spent some time updating the collaboration procedures about titles, keep issue head posts up to date, using labels, and lots of other wonderful things, I'm wondering if we've decided on where this document will sit in the tree? And whether the /build label is relevant in that case?
Btw, it occurs to me that a doc can reside anywhere in the tree and still appear anywhere else in the front. Maybe there was some confusing on that in earlier discussion. For example a doc like this could physical sit in the /development directory (since it concerns plugins) and still appear under the construction and presentation section of the index2.
Also, I notice @jools-r posted this in the forum, which seems quite relevant to the nature of this issue. I wonder if that's a sign that this has taken too long? I hate to see the forum used as a final destination for documentation. But that's just outlier me.
@Bloke @petecooper
I wonder if this might be re-titled to Updating plugins (or Updating orphaned plugins) and positioned immediately under the Developing plugins link that exists under the More section of Construction and Presentation of index2?
The title change only suggested due to the additional scope that Julian's how-to brings to it? Just a thought.
I hate to see the forum used as a final destination for documentation.
Zero barrier to entry for a veteran, I wouldn't take it as a sleight.
We could put it as a top-level doc in the 'More' area of index2. If this is solely for 'how to register a tag' then I can add the various methods. But if its reach is further, as 'updating (orphaned) plugins' suggests then I'm not sure what meaningful content we can add here.
There are a bajillion things that can go wrong with older plugins beyond lack of tag registration. Advances in PHP and MySQL mean function signatures change, classes might need updating to use __construct() instead of named constructors, errors are thrown (just like we found out in core this week) due to sloppy use of array indices, deprecated functionality such as dropping mysql_* calls, security improvements such as the changes to PASSWORD() in MySQL 8, the list goes on.
From Txp's perspective, the admin-side DOM changes regularly which affects many plugins - my own included (still) - we've dropped support for functions in lieu of constants (the is_windows() vs IS_WIN test, for example), we introduce new library classes to replace functional components, change or add callbacks, tighten the tag parser which causes invalid tag constructs to fail where they once worked, and so forth.
Trying to encompass all that in a doc with general hints on how to 'upgrade' a plugin might be a hiding to nowhere. We can highlight the most common, perhaps, if it's of value. But we'd need to then keep the doc up-to-date with not only our own changes but those of PHP and MySQL too.
Is there some scope-limitation we can do here to prevent digging ourselves into a huge maintenance quagmire?
There are a bajillion things that can go wrong with older plugins beyond lack of tag registration.
I retract my ill-informed questions. I was never here.
I wouldn't take it as a sleight.
I didn’t. I was speaking to the all-too-common situation of quality help info in the forum eventually sinking out of site (unless it’s a sticky), thus out of mind. Probably dozens to hundreds of quality help posts in the forum have lead to that fate. Can’t make that many stickies in the forum, nor is that what it’s for. But you know where you can? User docs. :)
Look, I get it. Were social animals. People gravitate to the forum for the interaction. I’m sometimes embarrassed that I have over 4500 posts there. It’s terrible. If I could clean that up, I would. The user docs site does not have that tempting interactive aspect. But neither is it supposed to; it’s meant for self-sufficiency and quiet productivity. It has a ways to go, though.
Also, I notice @jools-r posted this in the forum …I hate to see the forum used as a final destination for documentation.
Sorry, not always up to date on the various places where we have conversations. Yep, nothing intended by posting on the forum and I haven't yet properly perused your guidelines.
That particular how-to is specific to gocom's non-standard plugin setup so doesn't really concern "core docs". It could conceivably be a "txptip". It came about in response to another suggestion of mine on the forum that I then realized couldn't be followed through because gocom's plugins aren't available as "normal" compiled plugins. I thought I'd better provide a compiled version. As I've recently reformatted my own computer, I didn't have my own copy to hand and had to go through setting up gocom's compiler from scratch to create a compiled version … so I wrote down what I did while I was at it.
You did good, J, as you always do with your thoughtful and generous contributions to the community. Again, my only concern -- more accurately a soft desire -- is to bolster the docs.
In that aim, I sometimes don't make the best contributions to conversations, like this one, where the subject matter and scope is out of my jurisdiction. As I said to Stef, I was never here. Carry on.