From 6ab2a17a89c3ce37db8ed4ac4ff3fd3157e63aa8 Mon Sep 17 00:00:00 2001
From: Sipho Mkhwanazi <sipho411@gmail.com>
Date: Wed, 18 Feb 2026 20:07:30 +0200
Subject: [PATCH] Improve OSS metadata, packaging extras, and contributing
 guide

---
 CONTRIBUTING.md | 46 ++++++++++++++++++++++++++++++++++++++++++++--
 README.md       | 12 ++++++++++++
 pyproject.toml  | 11 +++++++----
 3 files changed, 63 insertions(+), 6 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6f2109e..c80e892 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,6 +7,13 @@ make install-dev
 make demo-migrate
 ```
 
+If you want local overrides:
+
+```bash
+cp .env.example .env
+make ENV_FILE=.env up
+```
+
 ## Run checks
 
 ```bash
@@ -14,9 +21,44 @@ 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.
diff --git a/README.md b/README.md
index 8dbcbd7..13e6e92 100644
--- a/README.md
+++ b/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
 
diff --git a/pyproject.toml b/pyproject.toml
index d3488e4..1627b28 100644
--- a/pyproject.toml
+++ b/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 = [