In my first article about Commentail, I explained why I started the library, what it can do and what changed in 0.1.1. Since then, 0.2.0 brought new features, followed by the stable 1.0.0 release.
What changed after 0.1.1
Before the stable release, also on October 19, I released version 0.2.0. It included several useful additions.
The new commentail_recent template tag lets you display recent comments on the homepage, in a sidebar or elsewhere on your site. You write the markup yourself. You can select comments from one page, limit their number and exclude replies. The query respects the visitor’s access to discussions, so the resulting block must not go into a shared cache for all users. Examples are in the recent comments guide.
German, French, Spanish and Brazilian Portuguese joined Russian and English. The interface, moderation settings and emails are translated. User comments themselves are not translated automatically.
Emails now have an HTML layout with a plain-text alternative. Comment settings are grouped in the admin interface, and moderators can use Wagtail search to choose a page.
I also worked on performance: reducing repeated queries, adding indexes and optimizing comment queries, rule processing and the email queue. Testing included synthetic datasets with one hundred thousand replies. The conditions and results are published in the performance report; speed on a particular site depends on its database, settings and workload.
Why I released a stable version
1.0.0 contains the same library code as 0.2.0, with no further behavior changes or migrations. The version I tested on my website was 0.2.0. Alongside automated tests, I checked real guest comments, moderation and emails in Gmail and Yandex. Upgrades and backup restoration were also tested. The scope of those checks and their findings are described in the testing report.
The main change in 1.0.0 is the published API stability and compatibility policy. Fixes in 1.0.x are not intended to break documented integrations, and new features in 1.x should remain backward compatible. Ordinary removal of a public API requires warnings in at least two minor releases and a transition period of at least six months; removal itself belongs in a new major version. The policy includes exceptions for urgent security fixes.
This is an important milestone for me: I had been thinking about a separate library for around two years, perhaps longer. It now runs on my website, and its usage and upgrade policies are documented. I decided there was no reason to keep postponing the stable release.
Upgrading to 1.0.0
The stable version is available on PyPI. If you already use 0.2.0, upgrading to 1.0.0 adds no new Commentail migrations. When upgrading from 0.1.1 or earlier, you also need to account for changes in the intervening releases: in particular, 0.2.0 adds database indexes.
Before upgrading, make a backup and test the upgrade on a test copy of your site. For a large database, measure how long index creation takes: the operation can block writes. The upgrade steps are collected in the installation guide.
If you try Commentail, tell me how it fits your site and what you found missing. If you find a bug, open an issue describing what happened and how to reproduce it. My next step is to develop the library with feedback from the people using it.
Choose a sign-in method or comment as a guest below.