Metadata-Version: 2.4
Name: splent_feature_comments
Version: 0.3.0
License-Expression: LGPL-3.0-or-later
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Requires-Dist: splent_framework>=1.20.0
Dynamic: license-file

# splent_feature_comments

The `comments` feature of a [SPLENT](https://splent.io) product line.

A SPLENT feature is a Python package that a product composes with others.
Its models, routes, services, templates and hooks are registered when the
product starts. What this feature provides and requires is listed in the
`[tool.splent.contract]` section of `pyproject.toml`, which
`splent feature:contract --write` keeps in sync with the source.

## What it does

Visitor comments on the posts of the `post` feature. The thread and its form
are drawn into each post through the `post.comments` hook, and the form
posts to `/comments/<post_id>`. The form shows only on a post the public can
read, as the post feature's `PostService.is_public` decides. A new comment
waits for moderation unless `COMMENTS_AUTO_APPROVE`, or the Comments
settings panel, publishes it at once. A captcha feature can veto a
submission through the `comment-submitting` signal.

The panel moderates the comments at `/admin/comments`, where they are
approved or deleted.

## Access

The screens under `/admin/comments` open for the accounts whose role is
`admin` or `staff`, the same pair the admin dashboard lets in. Any other
signed-in account gets 403 and does not see the Comments link in the
sidebar, and an anonymous visitor is sent to log in. Leaving a comment stays
open to everyone, signed in or not, on a post the public can read whose
comments are open. A draft or a scheduled post answers 404 to a comment, and
its preview in the panel shows the thread without the form.

There is no setting for these roles, and a refinement cannot replace the
views that check them, because it may add routes to this feature but never
replace one of its own. Another feature can decide for these screens with an
access policy registered for the prefix `comments.admin`
(`register_access_policy`, splent_framework 1.20.0). The framework asks the
policy before the roles. It answers True to let an account in, False to
refuse it, or None to leave the decision to the roles, and the sidebar link
follows the same answer. That is the way to let a group of accounts manage
only this section, for example the people who moderate the blog, without
giving them a panel role.
See [Access control](https://docs.splent.io/framework/access-control).

Without such a feature, give the person's account the staff role. Staff
opens every panel screen that asks for `PANEL_ROLES`, not only this one, so
a person who should moderate nothing but the comments needs a policy
instead.

```bash
splent feature:auth set-role someone@example.com staff
```

## Use it in a product

```bash
splent feature:add splent_feature_comments
```

## Develop

```bash
splent feature:test splent_feature_comments
splent feature:contract splent_feature_comments
```

## Release

```bash
splent feature:release splent_feature_comments --dry-run --bump patch
splent feature:release splent_feature_comments
```

The first command rehearses the release and changes nothing. The second
publishes it to the git forge and to PyPI, and a PyPI version is permanent.
