README Convention

AGENTS.md instructs the tools (AGENTS.md Convention); README.md explains the repo to a person. PyPI renders it as the package page, so it has to work outside GitHub too.

Why One Skeleton

The same headings in the same order let someone who lands from a search result or PyPI find installation, requirements and the license in any repo without reading it end to end. A repository released before this convention gets the skeleton and the metadata below with its next release.

The Skeleton

# <name>: the distribution name for Python packages (entirius-django-pim), the repo name otherwise.
One paragraph, first sentence ≤ 160 characters: what it is and what it does, in plain words, naming Entirius once with its descriptor (“the open-source modular ecommerce platform”). No product name without its explanation.
Badges line (PyPI version, Python versions, license) for Python packages; none elsewhere.
## What it does: 3 to 6 bullets, capabilities not internals.
## Installation: uv add <dist> / pip install <dist>; for Django modules the import name, INSTALLED_APPS, the URL include, required settings with a link to the settings reference.
## Quick start: a minimal, import-bearing example that matches the code at develop.
## Requirements: Python, Django, PostgreSQL where needed, sibling packages it pulls.
## Documentation: absolute links: the repo’s docs/ on GitHub, https://docs.entirius.com/, CHANGELOG.md.
## Part of Entirius: two lines and absolute links to the service, the harness and the closest sibling modules.
## Development: make install, make check, make test; absolute link to AGENTS.md.
## License: MPL-2.0.

Rules

Every link absolute (https://github.com/entirius/<repo>/blob/develop/…), because PyPI renders the file.
No status lines (“scaffold”, “unreleased”).
No version numbers in prose.
40 to 120 lines.
Non-Python repos drop items 3 and the pip lines and keep the order.

Metadata

Metadata in the same commit, in the [project] block of pyproject.toml:

description (≤ 120 characters, names Entirius);
keywords (5 to 8);
classifiers (exactly one development status: Development Status :: 5 - Production/Stable when the package version is 1.0 or higher, Development Status :: 4 - Beta below 1.0; framework, Python versions, license, topic);
project.urls (Homepage, Documentation, Repository, Changelog, Issues).

A README or metadata change needs no version bump and no changelog entry: it ships with the next release of the package.

[project]
description = "FAQ module for Entirius, the open-source modular ecommerce platform: grouped Q&A for the storefront"
keywords = ["entirius", "django", "faq", "ecommerce", "drf"]
classifiers = [
    "Development Status :: 5 - Production/Stable",
    "Framework :: Django",
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)",
    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
]

[project.urls]
Homepage = "https://docs.entirius.com/"
Documentation = "https://github.com/entirius/entirius-django-faq/blob/develop/docs/index.md"
Repository = "https://github.com/entirius/entirius-django-faq"
Changelog = "https://github.com/entirius/entirius-django-faq/blob/develop/CHANGELOG.md"
Issues = "https://github.com/entirius/entirius-django-faq/issues"

Example: Django Module

# entirius-django-faq

FAQ module for Entirius, the open-source modular ecommerce platform: questions and answers in groups, served to the storefront.
Each answer can be linked to a product or another entity and translated per language.

[![PyPI](https://img.shields.io/pypi/v/entirius-django-faq)](https://pypi.org/project/entirius-django-faq/) [![Python](https://img.shields.io/pypi/pyversions/entirius-django-faq)](https://pypi.org/project/entirius-django-faq/) [![License](https://img.shields.io/badge/license-MPL--2.0-blue)](https://github.com/entirius/entirius-django-faq/blob/develop/LICENSE)

## What it does

- Groups questions and answers, ordered by position, per sales channel.
- Serves active items to the storefront through a public API.
- Gives the CMS an admin API to edit groups, items and their translations.
- Links an item to a product, category or other entity by reference.

## Installation

```bash
uv add entirius-django-faq
```

Import name `django_faq`:

```python
INSTALLED_APPS = [..., "django_utils", "django_regional", "django_faq"]

urlpatterns = [..., path("", include("django_faq.urls"))]
```

The module reads no settings of its own. Channel scoping and the public API:
[docs](https://github.com/entirius/entirius-django-faq/blob/develop/docs/index.md).

## Quick start

```python
from django_faq.services.item_service import get_item_by_url_key

item = get_item_by_url_key(url_key="how-do-i-return-an-order", channel_idx="default", language_iso2="en")
```

## Requirements

- Python 3.11 or newer, Django 5.0 or newer
- Pulls `entirius-django-utils` and `entirius-django-regional`

## Documentation

- [Module docs](https://github.com/entirius/entirius-django-faq/blob/develop/docs/index.md)
- [Entirius documentation](https://docs.entirius.com/)
- [Changelog](https://github.com/entirius/entirius-django-faq/blob/develop/CHANGELOG.md)

## Part of Entirius

One module of the platform. It runs inside the [Volkanos service](https://github.com/entirius/entirius-service-volkanos)
and is tested in the [harness](https://github.com/entirius/entirius-zeno), next to [entirius-django-regional](https://github.com/entirius/entirius-django-regional).

## Development

```bash
make install
make check
make test
```

Agent and contributor instructions: [AGENTS.md](https://github.com/entirius/entirius-django-faq/blob/develop/AGENTS.md).

## License

MPL-2.0

Example: Library

# entirius-py-bievents

Business intelligence events for Entirius, the open-source modular ecommerce platform: structured JSON event logs on top of Python logging.
An event is a class; creating an instance writes one JSON line through a standard logging handler.

[![PyPI](https://img.shields.io/pypi/v/entirius-py-bievents)](https://pypi.org/project/entirius-py-bievents/) [![Python](https://img.shields.io/pypi/pyversions/entirius-py-bievents)](https://pypi.org/project/entirius-py-bievents/) [![License](https://img.shields.io/badge/license-MPL--2.0-blue)](https://github.com/entirius/entirius-py-bievents/blob/develop/LICENSE)

## What it does

- Defines business events as small classes with a type and a version.
- Writes each event as one JSON object through Python logging.
- Adds an id, start and end time and duration to every event.

## Installation

```bash
uv add entirius-py-bievents
```

## Quick start

```python
from bievents import BiEventAbstract


class OrderPlaced(BiEventAbstract):
    details_type = "Order placed"
    version = 1


OrderPlaced(source="checkout", business_unit="shop", environment="dev", status="success")
```

Attach `BiFormatter` to the `BI_LOGGER_NAME` logger to choose where the events go.

## Requirements

- Python 3.11 or newer
- Pulls `json-log-formatter`

## Documentation

- [Entirius documentation](https://docs.entirius.com/)
- [Changelog](https://github.com/entirius/entirius-py-bievents/blob/develop/CHANGELOG.md)

## Part of Entirius

A standalone library of the platform, used by the [Volkanos service](https://github.com/entirius/entirius-service-volkanos)
and tested in the [harness](https://github.com/entirius/entirius-zeno).

## Development

```bash
make install
make check
make test
```

Agent and contributor instructions: [AGENTS.md](https://github.com/entirius/entirius-py-bievents/blob/develop/AGENTS.md).

## License

MPL-2.0

Python Toolchain: the tools behind make install, make check and make test

Previous
AGENTS.md Convention Next
Python Toolchain