Sunsetting the Commentions plugin

[sebastiangreger]

Hi all,

as some may have noticed, work on v2 (on the develop branch) has stalled in beta for 1.5 years and all that has happened here were regular micro-updates to ensure v1 remains compatible with breaking changes in new Kirby releases. This is due to a lack of resources. Since this is permanent, and even allocating time for compatibility updates won't be possible in the future, I intend to retire the Commentions plugin as-is later this month.

This issue goes out to inform you, and to allow for anyone interested in taking over the project to speak up. I don't have a clear picture of what the user base might be, but there's maybe a low two-digit number of sites using v1 in production, and a handful of daredevils who verged into toying around with the v2 beta.

Maintaining v1 to "keep it alive" would probably be doable by regularly patching the code to keep up with the development of Kirby Core, Vue (incl. a looming move from Vue2 to Vue3 for the Kirby Panel), and new PHP versions. Support for older Kirby versions would likely have to be dropped eventually, as it introduces unnecessary intricacy. The v2 beta runs pretty reliably, but suffers from "feature creep" without the outstanding hard-handed cleanup that would turn an exploratory beta into a finalized, stable product (hence the stall in beta) – taking over that endeavor would be a significantly bigger commitment.

But of course "keeping Commentions running" is also possible in private: on your own copies, by hot-fixing a personal fork right within your project/site and based on your needs (without the overhead of maintaining a public project). It's not the cleanest library you'll have ever seen, but rather well documented/commented despite its complexity.

Unless somebody announces interest in taking over, I plan to archive this repo in its current state, with v1 as the default branch and the half-baked v2 tucked away in develop. This would allow anyone to dig out the code they need to keep their projects running until, potentially, migrating to some other solution or – thanks to the MIT license – to fork and refine it into an all-new offering.

Thank you all for your input and contributions over the past years, and my apologies for the inconvenience. Extra-special thanks to @fabianmichael without whose contributions this would never have seen the daylight in the first place. Please let me know if you have any suggestions or want to express interest in continuing the plugin's development.

[getflourish]

Thanks for your detailed information and also thank you for all the time that went into the plugin. Very inspiring to see communication like that. ❤️

[sebastiangreger]

With the arrival of Kirby 4.0, this plugin is officially out-of-date, with unfortunately no resources to keep it updated. Since nobody expressed interest to continue its development, this repository is today being archived. My apologies for any inconveniences caused, but as a spare time contribution to the Kirby community, supporting this plugin is no longer possible.

Some pointers for the way forward:

Resurrect and take over?

If you are interested to reactivate this plugin and become the project's maintainer, please get in touch!

Keeping it alive for yourself

One option to move forward is to keep hotfixing the plugin for your own needs:

• As the CMS evolves, breaking changes occur (for example, Kirby 4 drops the DS constant used everywhere in the plugin…); these can be identified based on error messages and fixed
• The panel API has changed quite a bit from K3 to K4, which would require some effort to restore the panel UIs
• Some of the libraries used during the Javascript build process are outdated or may have security issues; these would need to be reviewed and updated
• As new PHP versions are supported by Kirby, some of the code may need to be updated

While this is a lot of work to maintain as a published plugin, duct-taping it together for your individual needs may be pretty straightforward (you might even consider making such version available to others; the MIT license provides for that).

Exporting your data

All received comments and webmentions are stored in small commentions.yml files in a folder _commentions under each corresponding content folder (e.g. for page blog/2023/post-1 at blog/2023/post-1/_commentions/commentions.yml. To export all stored comments and webmentions, you may use the following snippet (this needs to be done before updating to Kirby 4+, as the Commentions plugin is only compatible with version 3.x):

// read all commentions and save to file `/site/logs/commentions-export.json`
foreach($site->index()->commentions('all')->toArray() as $commention) {
    $export[$commention['uid']] = $commention;
}
$export = json_encode($export, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
F::write(kirby()->root('logs') . '/commentions-export.json', $export);

This creates a JSON file /site/logs/commentions-export.json with all comment objects. The data fields are explained in this project's Readme file.

If you want to permanently remove all the data files created by Commentions, it is best to find and delete all _commentions folders within your content structure by using your operating system's command line tools. Ensure you have a complete backup in case things go awry.

Alternatives

At the moment of writing, Komments by @mauricerenck appears to be the only comment plugin for Kirby. It is in active development, compatible with Kirby 4, and pairs with the IndieConnector plugin to receive webmentions via webmention.io. There may be others popping up in the future; see https://getkirby.com/plugins for a current list.

Data migration from Commentions to Komments

Importing your Commentions data into Komments should be possible as follows:

• First make sure to create the data export as outlined above (before updating to Kirby 4!)
• Then make sure to uninstall the Commentions plugin and install the Komments plugin (as there are some code collisions)
• Next replace all the options, blueprint settings, template shortcodes, etc. with those described in the Komments installation guide
• To continue receiving incoming webmentions, you'll also have to install and setup the IndieConnector plugin

Once Komments is operational, you can create your individual import script.

NB. The following example code is for orientation only and comes without any promises or warranties; it has only been lightly tested and found to work for a very basic setup – you'll likely have to do some trial-and-error adjustments to suit your own needs, depending on your data, setup, environment etc. Also note that Komments is likely to evolve, requiring changes for any import routine. Always make sure to create a backup first and test this on a local instance (Komments writes comments and webmentions directly into your content files).

// baseline import script example for Komments
// for reference only - test, adjust and optimize for your own needs!
$kommentReceiver = new mauricerenck\Komments\KommentReceiver();
$commentions = json_decode(F::read(kirby()->root('logs') . '/commentions-export.json'), true);
foreach($commentions as $commention) {
    switch ($commention['type']) {
        case 'webmention': $type = 'MENTION'; break;
        case 'reply': $type = 'REPLY'; break;
        case 'like': $type = 'LIKE'; break;
        case 'repost': $type = 'REPOST'; break;
        case 'comment': $type = 'KOMMENT'; break;
        default: continue 2; // skip RSVP webmentions etc.
    }    
    $targetPage = $kirby->page($commention['pageid']);
    $newEntry = $kommentReceiver->createKomment(
        [
            'target' => $targetPage->url(),
            'source' => $type != 'KOMMENT' && !empty($commention['source']) ? $commention['source'] : $targetPage->url(),
            'published' => date('c', strtotime($commention['timestamp'])),
            'mentionOf' => null, // Commentions did not support threaded comments
            'type' => $type,
            'content' => $commention['text_sanitized'] ?? '',
            'quote' => null,
            'author' => [
                'type' => 'card',
                'name' => $commention['name_formatted'],
                'url' => $commention['website'] ?? null,
                'email' => $commention['email'] ?? null,
                'avatar' => $commention['avatar'] ?? null,
            ],
        ],
        0, // spamlevel
        !empty($commention['authenticated']) && $commention['authenticated'] === true, // isVerified
        $commention['status'] === 'approved', // autoPublish
    );
    $kommentReceiver->storeData($newEntry, $targetPage);
}

This solution ignores any RSVP webmentions etc., as they apparently are not supported in Komments' current version in the same way Commentions did. You could of course add your own logic to translate them into regular webmentions with a suitable textual representation ("Tim RSVP'd 'maybe'.").

Hint: You may have to extend this workflow to run the import in smaller chunks, if timeout errors occur on large amounts of comments.