Improve OSS metadata, packaging extras, and contributing guide

CONTRIBUTING.md

@@ -7,16 +7,58 @@ make install-dev
 make demo-migrate
 ```
 
+If you want local overrides:
+
+```bash
+cp .env.example .env
+make ENV_FILE=.env up
+```
+
 ## Run checks
 
 ```bash
 make qa
 make coverage
 ```
 
+## Branches and commits
+
+- Branch from `main` using `feature/<short-name>` or `fix/<short-name>`.
+- Keep commits focused and descriptive (imperative style).
+- Include tests in the same PR as behavior changes.
+
+## Testing paths
+
+- Fast smoke tests in Docker:
+  - `make test`
+- Full test suite in Docker:
+  - `make test-all`
+- One test target:
+  - `make test-one TEST=tests/test_api.py::test_catalog_and_checkout_flow`
+
+## Architecture expectations
+
+- Keep domain/business logic in service modules.
+- Keep views/viewsets thin.
+- Keep serializers focused on validation and representation.
+- Add migrations only for intentional schema changes.
+
+## Adding a new app/module
+
+- Create app code under `src/`.
+- Register the app in demo settings if demo exposure is required.
+- Mount routes from `productory_ecommerce.urls` when API surface changes.
+- Add tests in `tests/` for service and API behavior.
+- Update diagrams/docs in `docs/` if models or flows change.
+
+## Release notes
+
+- Update `CHANGELOG.md` for user-visible changes.
+- Tag releases using semantic versioning (`vMAJOR.MINOR.PATCH`).
+- Keep `pyproject.toml` metadata and README links in sync with the repo.
+
 ## Pull requests
 
 - Add or adjust tests for behavior changes.
-- Keep business logic in services.
-- Keep serializers focused on validation and transformation.
+- Describe behavior changes, migrations, and rollback considerations.
 - Use `make` targets in docs and examples for consistency.

README.md

@@ -2,6 +2,12 @@
 
 # Productory E-commerce
 
+[![CI](https://github.com/SipTech/productory/actions/workflows/ci.yml/badge.svg)](https://github.com/SipTech/productory/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/productory-ecommerce.svg)](https://pypi.org/project/productory-ecommerce/)
+[![Python](https://img.shields.io/pypi/pyversions/productory-ecommerce.svg)](https://pypi.org/project/productory-ecommerce/)
+[![Django](https://img.shields.io/badge/Django-4.2%20%7C%205.x-0C4B33)](https://www.djangoproject.com/)
+[![License](https://img.shields.io/pypi/l/productory-ecommerce.svg)](LICENSE)
+
 Reusable Django e-commerce building blocks with a working demo: catalog, checkout/orders, promotions, and store pricing config.
 
 ![Dark Mode Dashboard](docs/assets/branding/productory_dashboard_dark.png)
@@ -72,6 +78,12 @@ Mounted under `path("api/", include("productory_ecommerce.urls"))`:
 pip install productory-ecommerce
 ```
 
+Optional Postgres driver:
+
+```bash
+pip install "productory-ecommerce[postgres]"
+```
+
 ```python
 from django.urls import include, path
 

pyproject.toml

@@ -29,10 +29,12 @@ dependencies = [
   "Django>=4.2,<6.0",
   "djangorestframework>=3.14",
   "django-filter>=24.0",
-  "psycopg[binary]>=3.2",
 ]
 
 [project.optional-dependencies]
+postgres = [
+  "psycopg[binary]>=3.2",
+]
 dev = [
   "pytest>=8.0",
   "pytest-django>=4.8",
@@ -41,12 +43,13 @@ dev = [
   "coverage[toml]>=7.6",
   "djangorestframework-simplejwt>=5.4",
   "mypy>=1.11",
+  "psycopg[binary]>=3.2",
 ]
 
 [project.urls]
-Homepage = "https://github.com/productory/productory-ecommerce"
-Repository = "https://github.com/productory/productory-ecommerce"
-Issues = "https://github.com/productory/productory-ecommerce/issues"
+Homepage = "https://github.com/SipTech/productory"
+Repository = "https://github.com/SipTech/productory"
+Issues = "https://github.com/SipTech/productory/issues"
 
 [tool.hatch.build.targets.wheel]
 packages = [