Kerko

New features:

- Add the "Resource language" facet. It is disabled by default, but can be
enabled by setting the `kerko.facets.language.enabled` configuration parameter
to `true`. By default, Kerko will try to normalize the language names to make
the facet more usable; see `kerko.facets.language.` in the configuration
parameters documentation for details.

Removed features:

- Custom translation management commands that depended on Setuptools and
`setup.py` have been removed. Equivalent `pybabel` commands can be used
instead (see the updated Localization section of the documentation).

Other changes:

- Change the default configuration for some parameters:
- `kerko.facets.item_type.initial_limit`, now `10` instead of `0`.
- `kerko.facets.item_type.initial_limit_leeway`, now `4` instead of `2`.
- `kerko.facets.link.initial_limit_leeway`, now `0` instead of `2`.
- `kerko.facets.tag.initial_limit`, now `10` instead of `0`.
- `kerko.facets.tag.initial_limit_leeway`, now `4` instead of `2`.
- `kerko.facets.year.initial_limit_leeway`, now `0` instead of `2`.
- Update Portuguese translations. Thanks to Gonçalo Cordeiro.
- Move project metadata from `setup.cfg` to `pyproject.toml`.
- Build distribution package with Hatch instead of Setuptools.
- Use dynamic package versioning so that installers such as `pip` do not mistake
a development version for a previously published version. Version numbers are
now extracted from the tags and revisions of the Git repository.
- Reduce XML sitemaps size.
- Improve documentation.

Deprecated APIs:

- The Python variable `kerko.TRANSLATION_DIRECTORIES` is deprecated and will be
removed in Kerko 2.x. The variable `kerko.TRANSLATION_DIRECTORY` should be
used instead, and its type is a string instead of a list. If you are using a
custom application, please adapt it accordingly (you may check KerkoApp's
`__init__.py` for an example).

Features:

- Add Spanish translation. Thanks to [Albert
Ormazabal](https://github.com/aormazabal).

Bug fixes:

- Fix incorrect Docker image labels.
- Fix Docker run error, container lacking sufficient privileges (43).

Other changes:

- Add `help`, `requirements`, `requirements-upgrade`, and `upgrade` targets to
`Makefile`. These are helpers for KerkoApp development.
- Replace Yapf with Ruff formatter. Reformat whole code base.
- Add pre-commit hooks. Run Ruff and other code checks on pre-commit.
- Update the versions of pinned dependencies.
- Set container name on docker run.

Bug fixes:

- Fix Gunicorn not exiting if the application cannot start because of runtime
errors (such as configuration errors). Exit with the `errno.EINTR` error code.
- Fix duplicate log entries with syslog logging handler.

Backwards incompatible changes:

- Rename parameters in `sample.config.toml` following changes in Kerko.

Other changes:

- Add instance configuration file example, `sample.instance.toml`.
- Replace the base Docker image with the official Python 3.11 image, and update
Docker setup for Kerko 1.0.x.
- Improve the `Makefile` for an easier first-time experience using the Docker
image.
- Improve the `Makefile` for a simpler and more reliable Docker image building
process.
- Compile KerkoApp translations when building Docker image.

Changes:

- Add parameters to `sample.config.toml`.

Changes:

- Rename parameters in `sample.config.toml`.
- Print loaded configuration file paths in debug mode only.
- Rename the default branch of the repository from 'master' to 'main'. If you
have cloned the repository with Git and were using the `master` branch, use
the following commands to rename your local branch:

bash
git branch -m master main
git fetch origin
git branch -u origin/main main
git remote set-head origin -a

*Warning:* Upgrading from version 0.9 or earlier will require that you adapt
your installation and configuration files (see changes descriptions below),
rebuild your search index using the following commands, and then restart the
application:

bash
flask kerko clean index
flask kerko sync index


Features:

- TOML files are now the preferred way of configuring KerkoApp. Since the
configuration structure has also greatly changed, it is recommended that you
review all your settings from `.env` files and migrate them to TOML files.
Please refer to the Kerko documentation on configuration.
- Add many new configuration parameters. Consequently, many more customizations
are now possible without having to replace KerkoApp with a custom application.
Please refer to Kerko's documentation for the full list of options.

Other changes:

- Restructure and expand documentation into a unified documentation site for
both Kerko and KerkoApp.
- Add Portuguese translation. Thanks to Gonçalo Cordeiro.
- Update the versions of pinned dependencies.

Backwards incompatible changes:

- Rename `kerkoapp.py` to `wsgi.py`, which is a more convenient default that, in
many cases, makes it unnecessary to set the `FLASK_APP` environment variable
or the `--app` command line option. You may need to unset or change your
`FLASK_APP` environment variable, and/or adapt your WSGI server's
configuration to refer to the new location of the application object, which is
now `wsgi.app` instead of `kerkoapp.app`.
- Rename the `app` directory to `kerkoapp` to avoid potential name ambiguity
with the `app` object.
- Remove all uses of the `FLASK_ENV` configuration variable, which Flask 2.3
stopped supporting. For debug mode, use Flask's `--debug` command line option.
- The data directory has a new default location relative to the instance path.
Please check the documentation for the `DATA_PATH` and `INSTANCE_PATH`
configuration parameters. You may need to set one or both of those parameters,
and/or move your existing data directory.
- Almost all configuration parameters have been renamed and/or moved into a
hierarchical structure. Hierarchical parameters are referred to using
path-like, dot-separated parameter names, and may conveniently be set with the
`kerko.config_helpers.config_set()` function. Here is a mapping of the changed
parameters that are specific to KerkoApp (please check also Kerko's changelog
for other parameter changes):
- `KERKOAPP_CHILD_EXCLUDE_RE` → `kerko.zotero.child_exclude_re`
- `KERKOAPP_CHILD_INCLUDE_RE` → `kerko.zotero.child_include_re`
- `KERKOAPP_COLLECTION_FACETS` → `kerko.facets.*`. See sub-parameters `type`
(set it to `"collection"`), `collection_key`, and `title`.
- `KERKOAPP_EXCLUDE_DEFAULT_BADGES`: Removed, with no replacement since no
default badges are provided at this point.
- `KERKOAPP_EXCLUDE_DEFAULT_CITATION_FORMATS` → `kerko.citation_formats.*`.
See sub-parameter `enable`.
- `KERKOAPP_EXCLUDE_DEFAULT_FACETS` → `kerko.facets.*`. See sub-parameter
`enable`.
- `KERKOAPP_EXCLUDE_DEFAULT_FIELDS` → `kerko.search_fields.*`. See
sub-parameter `enable`.
- `KERKOAPP_EXCLUDE_DEFAULT_SCOPES` → `kerko.scopes.*`. See sub-parameter
`enable`.
- `KERKOAPP_EXCLUDE_DEFAULT_SORTS` → `kerko.sorts.*`. See sub-parameter
`enable`.
- `KERKOAPP_FACET_INITIAL_LIMIT_LEEWAY` →
`kerko.facets.*.initial_limit_leeway`. This is now set individually for
each facet, and there is no longer a global parameter.
- `KERKOAPP_FACET_INITIAL_LIMIT` → `kerko.facets.*.initial_limit`. This is
now set individually for each facet, and there is no longer a global
parameter.
- `KERKOAPP_ITEM_EXCLUDE_RE` → `kerko.zotero.item_exclude_re`
- `KERKOAPP_ITEM_INCLUDE_RE` → `kerko.zotero.item_include_re`
- `KERKOAPP_MIME_TYPES` → `kerko.zotero.attachment_mime_types`
- `KERKOAPP_TAG_EXCLUDE_RE` → `kerko.zotero.tag_exclude_re`
- `KERKOAPP_TAG_INCLUDE_RE` → `kerko.zotero.tag_include_re`
- `PROXY_FIX` → `kerkoapp.proxy_fix.*`