wagtail-seeder 1.0.0__tar.gz

wagtail_seeder-1.0.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Four Digits
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

wagtail_seeder-1.0.0/MANIFEST.in

@@ -0,0 +1,10 @@
+recursive-include src/wagtail_seeder/templates *.html
+recursive-include src/wagtail_seeder/static *.css *.js
+include README.md LICENSE
+include docs/compatibility.md
+prune tests
+prune documents
+prune original_images
+prune build
+prune dist
+global-exclude __pycache__ *.py[cod] *.sqlite3

wagtail_seeder-1.0.0/PKG-INFO

@@ -0,0 +1,334 @@
+Metadata-Version: 2.4
+Name: wagtail-seeder
+Version: 1.0.0
+Summary: Safe development-data seeding for Wagtail projects.
+Author: Four Digits
+License-Expression: BSD-3-Clause
+Classifier: Framework :: Django
+Classifier: Framework :: Wagtail
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: wagtail<8,>=7
+Requires-Dist: Faker>=24
+Requires-Dist: Pillow>=10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-django>=4.8; extra == "dev"
+Requires-Dist: psycopg[binary]>=3.1; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: twine>=6.1; extra == "dev"
+Dynamic: license-file
+
+# Wagtail Seeder
+
+Development-data seeder for Wagtail 7.x (Python 3.10 and later). It creates representative
+pages, media, snippets and settings by inspecting installed Wagtail models.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+python -m pip install wagtail-seeder
+```
+
+Add `"wagtail_seeder"` to `INSTALLED_APPS`. Configure
+an explicit environment; the package fails closed when it is omitted or unsupported:
+
+```python
+WAGTAIL_SEEDER = {
+    "ENVIRONMENT": "dev",
+    "HOMEPAGE_MODEL": "pages.HomePage",
+    "DEFAULT_SITE_PORT": 80,  # use 8000 for Django's runserver
+}
+```
+
+Apply the project's migrations, then inspect and seed:
+
+```bash
+python manage.py migrate
+python manage.py inspect_wagtail_seed --format=json --require-complete
+python manage.py seed_wagtail --confirm --require-complete
+python manage.py seed_wagtail_pages --page-type pages.ArticlePage
+```
+
+`seed_wagtail` is destructive: it removes Wagtail `Site` objects and pages below
+its technical root. Use an isolated development database. `seed_wagtail_pages`
+preserves existing pages and reuses representatives when the configured count is met.
+During a full reset, nullable protected links into the old page tree are detached
+and populated again. Required protected links block deletion; the original sites,
+pages and detached links are restored when deletion fails.
+The same actions are available through **Seeder** in the Wagtail admin to active
+users with the explicitly assigned `wagtail_seeder.run_seeder` permission.
+Superusers also need a direct or group grant; their automatic Django permission
+bypass does not apply. Existing users are not granted access on upgrade.
+CLI commands require the explicit allowed environment and do not impersonate a user.
+
+After `migrate`, assign **Can run Wagtail Seeder** through Django's user/group
+administration or Wagtail's group permissions. Users also need normal Wagtail
+admin access. Removing the grant immediately hides the menu and blocks seed requests.
+
+The dashboard includes a moving loading bar and elapsed time during a seed,
+searchable page selection, and a searchable, sortable result table with status
+filters. The loading bar indicates activity rather than a completion percentage.
+The last report remains available after refreshing until the next seed. Report
+items include `is_summary` (default `False`); summary rows are excluded from
+outcome counts so a failure is counted once.
+
+## Sites and languages
+
+A single-site project needs only the configuration above. Use `SITE_ROOTS` for
+multiple public sites or languages. Every root creates its own `Site`; descendants,
+page links, settings and translatable snippets stay within their applicable scope.
+
+```python
+WAGTAIL_SEEDER = {
+    "ENVIRONMENT": "dev",
+    "DEFAULT_SITE_PORT": 80,
+    "SITE_ROOTS": [
+        {
+            "page_model": "pages.HomePage",
+            "hostname": "localhost",
+            "language_code": "nl",
+            "is_default_site": True,
+        },
+        {
+            "page_model": "pages.HomePage",
+            "hostname": "en.localhost",
+            "language_code": "en",
+        },
+    ],
+}
+```
+
+`language_code` must be in Wagtail's content languages. It resolves or creates a
+`Locale`; it does not enable translation settings or translate text. Omit it to use
+the project's default content language. Do not put a language string in
+`field_values["locale"]`: that field expects a `Locale` instance.
+
+Each root requires `page_model`; optional values include `hostname`, `port`,
+`site_name`, `is_default_site`, `slug` and protected `field_values`. Give it a unique
+`key` when another configured root uses `parent_page_key`.
+
+`SEED_ROOT_PAGES` uses the same page configuration without creating another Site.
+Use it only for technical branches that otherwise cannot be reached.
+`parent_page_model` or `parent_page_key` deliberately selects an explicit parent;
+`force_root: True` deliberately overrides creation restrictions at the technical
+root. An explicit parent and `force_root` cannot be combined.
+
+## Generation and validation
+
+The seeder creates draft page structures before filling dependencies and publishing.
+Editor presets keep their existing text and structure while empty required fields
+and nested blocks are filled. Existing valid relationships are preserved, including
+relationships in explicitly declared many-to-many intermediate models.
+Scalar fields required by the page editor are filled even when the model permits
+blank values, without changing the model's field definitions.
+It uses Wagtail's allowed parent/child models, `can_create_at()`, global `max_count`
+and per-parent limits. Titles come from model names: `NewsOverviewPage` becomes
+**News Overview**. Valid defaults and populated content are retained, including
+visibility flags, locales, translation keys and configured values.
+
+`PAGE_COUNTS` maps model labels to positive counts **per public tree and locale**;
+the default is one of each applicable concrete type. A subclass does not count as
+its parent type. Wagtail's global singleton limits still take precedence.
+`UNIQUE_PAGE_SCOPES` adds post-seed checks for combinations of `site`, `region`
+and/or `language`.
+
+Stream/List blocks and InlinePanels follow their minimum/maximum counts, including
+nested `block_counts`. `REQUIRED_STREAMFIELD_ITEM_COUNTS` supplies additional
+business constraints not declared on the block:
+
+```python
+"REQUIRED_STREAMFIELD_ITEM_COUNTS": {"pages.ArticlePage.highlights": 2}
+```
+
+`SNIPPET_COUNTS` accepts model labels or legacy class names (labels take precedence).
+The default is four; use zero to request no new instances. Translatable snippets
+are generated for every configured root locale. Existing instances are reused and
+validated, and stale chooser links are repaired without replacing their text.
+Site settings are populated before saving, then revisited after their hooks have
+created any additional pages. Page-owned inlines keep their original parent.
+
+When `wagtailstreamforms` is installed, the seeder builds local contact forms from
+registered single-line, email and multiline field blocks and configured templates.
+It also supports older installations with separate FormField models. Submission
+hooks stay empty; the seeder does not submit forms or send mail.
+
+The inspector only reads configuration and model structure; it does not execute
+model validation or prove rendering works. `seed_wagtail --require-complete` checks
+both that graph and the results of actual model/block validation. Missing mandatory
+content fails the command. Optional unsupported blocks/inlines are reported as
+skipped; declared exclusions are intentional. Failed objects are rolled back,
+while successful objects remain available for diagnosis.
+
+## Small project providers
+
+Use providers for business rules that cannot be inferred from field declarations.
+Keep them in the consuming project and configure dotted paths:
+
+```python
+"MODEL_VALUE_PROVIDERS": ["myproject.seeding.model_values"],
+"FIELD_VALUE_PROVIDERS": ["myproject.seeding.field_values"],
+"BLOCK_VALUE_PROVIDERS": ["myproject.seeding.block_values"],
+```
+
+Model providers receive `(instance, context)` during `prepare` (before generic
+population) and `validate` (before validation). Make them idempotent. Field providers
+receive `(instance, field, context)` during `pre`/`post`, including relation and
+StreamField fields. Block providers receive `(block, context)`. Field and block
+providers return `wagtail_seeder.providers.UNHANDLED` to delegate generation;
+returning `None` intentionally supplies an empty value.
+
+Context includes `seeder`, `config`, scoped `pages`, `phase`, `instance`/`owner`,
+`site`, `locale`, a zero-based `index`, `field_name` and a tuple `block_path`.
+For model providers, `index` is stable within the model's ordered instances and
+locale scope. For nested block providers it identifies the current stream/list item.
+Protected `field_values` bypass generic field generation and link repair; model
+providers may deliberately change them.
+
+For example, a project that retrieves exactly one navigation object per language
+can assign the configured languages using the model provider's index. Match
+`SNIPPET_COUNTS` to the number of languages. See the
+[configuration guide](docs/compatibility.md) for generic examples covering multiple
+sites, custom validation, technical page types and external dependencies.
+
+## External integrations
+
+Exclude models and blocks whose validation or rendering needs an external service:
+
+```python
+"EXCLUDED_SNIPPET_MODELS": ["newsletter.MailingList"],
+"SKIP_BLOCK_CLASS_NAMES": {"NewsletterBlock": "requires an external service"},
+```
+
+Exclusions also apply to indirect chooser/required-relation creation. Block exclusions
+match class names, qualified names and subclasses. A required excluded dependency
+is an error; a provider or a different valid local block is needed. External optional
+video URL fields with empty valid defaults stay empty. Seeder settings cannot turn
+off network calls hardcoded in a project's page rendering or save hooks.
+
+Other optional keys are `ALLOWED_ENVIRONMENTS` (default `{"dev"}`),
+`ALLOWED_HOSTNAMES` (dashboard request guard), `FAKER_LOCALE` (default `"nl_NL"`),
+`DEFAULT_SITE_HOSTNAME` (default `"localhost"`) and `DEFAULT_SITE_PORT`
+(default `8000`). Complete local compatibility requires testing the generated
+frontend and editor in the consuming project; static inspection cannot guarantee
+arbitrary custom validation or JavaScript behavior.
+
+## Development and testing
+
+The repository separates the distributable package from its local test project:
+
+```text
+src/wagtail_seeder/    Python package, management commands and admin templates
+tests/test_project/   Runnable Django/Wagtail project, local database and media
+tests/models.py       Example page and relation models
+tests/migrations/     One initial migration for the example models
+tests/test_*.py       Automated tests
+```
+
+From the repository root, create an environment and install the package in editable
+mode. Changes in `src` then take effect immediately:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+pytest
+```
+
+The default installation uses the latest available Wagtail 7.x. To test the lowest
+supported release series, use a separate environment and install with
+`python -m pip install -e ".[dev]" "wagtail>=7,<7.1"`.
+
+Run the same checks as CI:
+
+```bash
+python tests/test_project/manage.py check
+python tests/test_project/manage.py makemigrations --check --dry-run
+ruff check .
+ruff format --check .
+pytest
+```
+
+Automated tests use an isolated database and temporary media directories. They do
+not change the local demo database or leave generated media in the repository root.
+
+## Local Wagtail project
+
+No external project or Bakery Demo checkout is required. From the repository root:
+
+```bash
+python tests/test_project/manage.py migrate
+python tests/test_project/manage.py createsuperuser
+python tests/test_project/manage.py inspect_wagtail_seed --require-complete
+python tests/test_project/manage.py seed_wagtail --confirm --require-complete
+python tests/test_project/manage.py runserver
+```
+
+Open `http://127.0.0.1:8000/admin/` and log in. Explicitly assign **Can run Wagtail
+Seeder** to the account or its group before opening **Seeder** in the menu.
+Visit `http://127.0.0.1:8000/admin/seeder/` to test a full seed or
+selected page types. The confirmation checkbox is required for a destructive full
+seed. Open `http://127.0.0.1:8000/` to browse the generated pages.
+
+For example, test the selective command with:
+
+```bash
+python tests/test_project/manage.py seed_wagtail_pages --page-type tests.ArticlePage
+```
+
+The local database, uploaded/generated media and collected static files live under
+`tests/test_project/` and are ignored by Git. The project is configured for local
+development only.
+The example models use one initial migration. If a local demo database was created
+with the previous migration layout, recreate that demo database before migrating.
+Installed packages continue to use the separate `wagtail_seeder` permission migration.
+
+## Building and releasing
+
+Build the wheel and source distribution and check their metadata:
+
+```bash
+python -m build
+python -m twine check dist/*
+python scripts/check_distribution.py
+tar -tf dist/wagtail_seeder-*.tar.gz
+unzip -l dist/wagtail_seeder-*.whl
+```
+
+Before publishing, install the built wheel in the target project's environment
+with `python -m pip install /path/to/wagtail_seeder-1.0.0-py3-none-any.whl`, then
+apply migrations and the local Seeder configuration. Check a full seed, selective
+seeding, frontend rendering and saving generated pages in the editor. This tests
+the packaged assets and any custom validation in the application.
+
+Runtime code and templates come from `src/wagtail_seeder/`. Tests, demo databases
+and media are excluded from both distributions. The source archive also contains
+the README, license and build metadata.
+
+Public releases are published from GitLab CI to PyPI using
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/).
+Before the first release, configure a pending publisher on PyPI (or a publisher
+on the existing project) with:
+
+- PyPI project: `wagtail-seeder`
+- GitLab namespace: `fourdigits/private-packages`
+- GitLab project: `wagtail-seeder`
+- Pipeline file: `.gitlab-ci.yml`
+- Environment: `pypi`
+
+Protect the `v*` tag pattern in GitLab. No stored PyPI API token is needed.
+Update the version in the project metadata and
+`src/wagtail_seeder/__init__.py`, then push a protected tag matching that version,
+for example `v1.0.0`. CI requires the tag and both version declarations to agree,
+and publishes only after tests and package checks pass. Published versions cannot
+be overwritten; bump the version for each new release.
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).

wagtail_seeder-1.0.0/README.md

@@ -0,0 +1,309 @@
+# Wagtail Seeder
+
+Development-data seeder for Wagtail 7.x (Python 3.10 and later). It creates representative
+pages, media, snippets and settings by inspecting installed Wagtail models.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+python -m pip install wagtail-seeder
+```
+
+Add `"wagtail_seeder"` to `INSTALLED_APPS`. Configure
+an explicit environment; the package fails closed when it is omitted or unsupported:
+
+```python
+WAGTAIL_SEEDER = {
+    "ENVIRONMENT": "dev",
+    "HOMEPAGE_MODEL": "pages.HomePage",
+    "DEFAULT_SITE_PORT": 80,  # use 8000 for Django's runserver
+}
+```
+
+Apply the project's migrations, then inspect and seed:
+
+```bash
+python manage.py migrate
+python manage.py inspect_wagtail_seed --format=json --require-complete
+python manage.py seed_wagtail --confirm --require-complete
+python manage.py seed_wagtail_pages --page-type pages.ArticlePage
+```
+
+`seed_wagtail` is destructive: it removes Wagtail `Site` objects and pages below
+its technical root. Use an isolated development database. `seed_wagtail_pages`
+preserves existing pages and reuses representatives when the configured count is met.
+During a full reset, nullable protected links into the old page tree are detached
+and populated again. Required protected links block deletion; the original sites,
+pages and detached links are restored when deletion fails.
+The same actions are available through **Seeder** in the Wagtail admin to active
+users with the explicitly assigned `wagtail_seeder.run_seeder` permission.
+Superusers also need a direct or group grant; their automatic Django permission
+bypass does not apply. Existing users are not granted access on upgrade.
+CLI commands require the explicit allowed environment and do not impersonate a user.
+
+After `migrate`, assign **Can run Wagtail Seeder** through Django's user/group
+administration or Wagtail's group permissions. Users also need normal Wagtail
+admin access. Removing the grant immediately hides the menu and blocks seed requests.
+
+The dashboard includes a moving loading bar and elapsed time during a seed,
+searchable page selection, and a searchable, sortable result table with status
+filters. The loading bar indicates activity rather than a completion percentage.
+The last report remains available after refreshing until the next seed. Report
+items include `is_summary` (default `False`); summary rows are excluded from
+outcome counts so a failure is counted once.
+
+## Sites and languages
+
+A single-site project needs only the configuration above. Use `SITE_ROOTS` for
+multiple public sites or languages. Every root creates its own `Site`; descendants,
+page links, settings and translatable snippets stay within their applicable scope.
+
+```python
+WAGTAIL_SEEDER = {
+    "ENVIRONMENT": "dev",
+    "DEFAULT_SITE_PORT": 80,
+    "SITE_ROOTS": [
+        {
+            "page_model": "pages.HomePage",
+            "hostname": "localhost",
+            "language_code": "nl",
+            "is_default_site": True,
+        },
+        {
+            "page_model": "pages.HomePage",
+            "hostname": "en.localhost",
+            "language_code": "en",
+        },
+    ],
+}
+```
+
+`language_code` must be in Wagtail's content languages. It resolves or creates a
+`Locale`; it does not enable translation settings or translate text. Omit it to use
+the project's default content language. Do not put a language string in
+`field_values["locale"]`: that field expects a `Locale` instance.
+
+Each root requires `page_model`; optional values include `hostname`, `port`,
+`site_name`, `is_default_site`, `slug` and protected `field_values`. Give it a unique
+`key` when another configured root uses `parent_page_key`.
+
+`SEED_ROOT_PAGES` uses the same page configuration without creating another Site.
+Use it only for technical branches that otherwise cannot be reached.
+`parent_page_model` or `parent_page_key` deliberately selects an explicit parent;
+`force_root: True` deliberately overrides creation restrictions at the technical
+root. An explicit parent and `force_root` cannot be combined.
+
+## Generation and validation
+
+The seeder creates draft page structures before filling dependencies and publishing.
+Editor presets keep their existing text and structure while empty required fields
+and nested blocks are filled. Existing valid relationships are preserved, including
+relationships in explicitly declared many-to-many intermediate models.
+Scalar fields required by the page editor are filled even when the model permits
+blank values, without changing the model's field definitions.
+It uses Wagtail's allowed parent/child models, `can_create_at()`, global `max_count`
+and per-parent limits. Titles come from model names: `NewsOverviewPage` becomes
+**News Overview**. Valid defaults and populated content are retained, including
+visibility flags, locales, translation keys and configured values.
+
+`PAGE_COUNTS` maps model labels to positive counts **per public tree and locale**;
+the default is one of each applicable concrete type. A subclass does not count as
+its parent type. Wagtail's global singleton limits still take precedence.
+`UNIQUE_PAGE_SCOPES` adds post-seed checks for combinations of `site`, `region`
+and/or `language`.
+
+Stream/List blocks and InlinePanels follow their minimum/maximum counts, including
+nested `block_counts`. `REQUIRED_STREAMFIELD_ITEM_COUNTS` supplies additional
+business constraints not declared on the block:
+
+```python
+"REQUIRED_STREAMFIELD_ITEM_COUNTS": {"pages.ArticlePage.highlights": 2}
+```
+
+`SNIPPET_COUNTS` accepts model labels or legacy class names (labels take precedence).
+The default is four; use zero to request no new instances. Translatable snippets
+are generated for every configured root locale. Existing instances are reused and
+validated, and stale chooser links are repaired without replacing their text.
+Site settings are populated before saving, then revisited after their hooks have
+created any additional pages. Page-owned inlines keep their original parent.
+
+When `wagtailstreamforms` is installed, the seeder builds local contact forms from
+registered single-line, email and multiline field blocks and configured templates.
+It also supports older installations with separate FormField models. Submission
+hooks stay empty; the seeder does not submit forms or send mail.
+
+The inspector only reads configuration and model structure; it does not execute
+model validation or prove rendering works. `seed_wagtail --require-complete` checks
+both that graph and the results of actual model/block validation. Missing mandatory
+content fails the command. Optional unsupported blocks/inlines are reported as
+skipped; declared exclusions are intentional. Failed objects are rolled back,
+while successful objects remain available for diagnosis.
+
+## Small project providers
+
+Use providers for business rules that cannot be inferred from field declarations.
+Keep them in the consuming project and configure dotted paths:
+
+```python
+"MODEL_VALUE_PROVIDERS": ["myproject.seeding.model_values"],
+"FIELD_VALUE_PROVIDERS": ["myproject.seeding.field_values"],
+"BLOCK_VALUE_PROVIDERS": ["myproject.seeding.block_values"],
+```
+
+Model providers receive `(instance, context)` during `prepare` (before generic
+population) and `validate` (before validation). Make them idempotent. Field providers
+receive `(instance, field, context)` during `pre`/`post`, including relation and
+StreamField fields. Block providers receive `(block, context)`. Field and block
+providers return `wagtail_seeder.providers.UNHANDLED` to delegate generation;
+returning `None` intentionally supplies an empty value.
+
+Context includes `seeder`, `config`, scoped `pages`, `phase`, `instance`/`owner`,
+`site`, `locale`, a zero-based `index`, `field_name` and a tuple `block_path`.
+For model providers, `index` is stable within the model's ordered instances and
+locale scope. For nested block providers it identifies the current stream/list item.
+Protected `field_values` bypass generic field generation and link repair; model
+providers may deliberately change them.
+
+For example, a project that retrieves exactly one navigation object per language
+can assign the configured languages using the model provider's index. Match
+`SNIPPET_COUNTS` to the number of languages. See the
+[configuration guide](docs/compatibility.md) for generic examples covering multiple
+sites, custom validation, technical page types and external dependencies.
+
+## External integrations
+
+Exclude models and blocks whose validation or rendering needs an external service:
+
+```python
+"EXCLUDED_SNIPPET_MODELS": ["newsletter.MailingList"],
+"SKIP_BLOCK_CLASS_NAMES": {"NewsletterBlock": "requires an external service"},
+```
+
+Exclusions also apply to indirect chooser/required-relation creation. Block exclusions
+match class names, qualified names and subclasses. A required excluded dependency
+is an error; a provider or a different valid local block is needed. External optional
+video URL fields with empty valid defaults stay empty. Seeder settings cannot turn
+off network calls hardcoded in a project's page rendering or save hooks.
+
+Other optional keys are `ALLOWED_ENVIRONMENTS` (default `{"dev"}`),
+`ALLOWED_HOSTNAMES` (dashboard request guard), `FAKER_LOCALE` (default `"nl_NL"`),
+`DEFAULT_SITE_HOSTNAME` (default `"localhost"`) and `DEFAULT_SITE_PORT`
+(default `8000`). Complete local compatibility requires testing the generated
+frontend and editor in the consuming project; static inspection cannot guarantee
+arbitrary custom validation or JavaScript behavior.
+
+## Development and testing
+
+The repository separates the distributable package from its local test project:
+
+```text
+src/wagtail_seeder/    Python package, management commands and admin templates
+tests/test_project/   Runnable Django/Wagtail project, local database and media
+tests/models.py       Example page and relation models
+tests/migrations/     One initial migration for the example models
+tests/test_*.py       Automated tests
+```
+
+From the repository root, create an environment and install the package in editable
+mode. Changes in `src` then take effect immediately:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+pytest
+```
+
+The default installation uses the latest available Wagtail 7.x. To test the lowest
+supported release series, use a separate environment and install with
+`python -m pip install -e ".[dev]" "wagtail>=7,<7.1"`.
+
+Run the same checks as CI:
+
+```bash
+python tests/test_project/manage.py check
+python tests/test_project/manage.py makemigrations --check --dry-run
+ruff check .
+ruff format --check .
+pytest
+```
+
+Automated tests use an isolated database and temporary media directories. They do
+not change the local demo database or leave generated media in the repository root.
+
+## Local Wagtail project
+
+No external project or Bakery Demo checkout is required. From the repository root:
+
+```bash
+python tests/test_project/manage.py migrate
+python tests/test_project/manage.py createsuperuser
+python tests/test_project/manage.py inspect_wagtail_seed --require-complete
+python tests/test_project/manage.py seed_wagtail --confirm --require-complete
+python tests/test_project/manage.py runserver
+```
+
+Open `http://127.0.0.1:8000/admin/` and log in. Explicitly assign **Can run Wagtail
+Seeder** to the account or its group before opening **Seeder** in the menu.
+Visit `http://127.0.0.1:8000/admin/seeder/` to test a full seed or
+selected page types. The confirmation checkbox is required for a destructive full
+seed. Open `http://127.0.0.1:8000/` to browse the generated pages.
+
+For example, test the selective command with:
+
+```bash
+python tests/test_project/manage.py seed_wagtail_pages --page-type tests.ArticlePage
+```
+
+The local database, uploaded/generated media and collected static files live under
+`tests/test_project/` and are ignored by Git. The project is configured for local
+development only.
+The example models use one initial migration. If a local demo database was created
+with the previous migration layout, recreate that demo database before migrating.
+Installed packages continue to use the separate `wagtail_seeder` permission migration.
+
+## Building and releasing
+
+Build the wheel and source distribution and check their metadata:
+
+```bash
+python -m build
+python -m twine check dist/*
+python scripts/check_distribution.py
+tar -tf dist/wagtail_seeder-*.tar.gz
+unzip -l dist/wagtail_seeder-*.whl
+```
+
+Before publishing, install the built wheel in the target project's environment
+with `python -m pip install /path/to/wagtail_seeder-1.0.0-py3-none-any.whl`, then
+apply migrations and the local Seeder configuration. Check a full seed, selective
+seeding, frontend rendering and saving generated pages in the editor. This tests
+the packaged assets and any custom validation in the application.
+
+Runtime code and templates come from `src/wagtail_seeder/`. Tests, demo databases
+and media are excluded from both distributions. The source archive also contains
+the README, license and build metadata.
+
+Public releases are published from GitLab CI to PyPI using
+[Trusted Publishing](https://docs.pypi.org/trusted-publishers/using-a-publisher/).
+Before the first release, configure a pending publisher on PyPI (or a publisher
+on the existing project) with:
+
+- PyPI project: `wagtail-seeder`
+- GitLab namespace: `fourdigits/private-packages`
+- GitLab project: `wagtail-seeder`
+- Pipeline file: `.gitlab-ci.yml`
+- Environment: `pypi`
+
+Protect the `v*` tag pattern in GitLab. No stored PyPI API token is needed.
+Update the version in the project metadata and
+`src/wagtail_seeder/__init__.py`, then push a protected tag matching that version,
+for example `v1.0.0`. CI requires the tag and both version declarations to agree,
+and publishes only after tests and package checks pass. Published versions cannot
+be overwritten; bump the version for each new release.
+
+## License
+
+BSD-3-Clause. See [LICENSE](LICENSE).