Update: best-practices repo with docs, CI, tests, and latest deps

.env.example

@@ -0,0 +1,16 @@
+# BridgeStack Environment Configuration
+# Copy this file to .env and modify as needed.
+# All variables are prefixed with BRIDGE_ to avoid conflicts.
+
+# Database connection string (SQLite default; can be changed to PostgreSQL)
+BRIDGE_DATABASE_URL=sqlite:///./rootstack.db
+
+# Enable debug mode (true/false)
+BRIDGE_DEBUG=false
+
+# Allowed CORS origins (JSON array)
+# Use ["*"] for development, restrict in production
+BRIDGE_CORS_ORIGINS=["http://localhost:3000","http://localhost:5173"]
+
+# Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+BRIDGE_LOG_LEVEL=INFO

.github/workflows/ci.yml

@@ -7,15 +7,48 @@ on:
     branches: [main]
 
 jobs:
-  validate:
+  lint:
+    name: Lint & Format
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: '3.12'
-      - name: Check Python syntax
-        run: python -m py_compile $(find . -name "*.py" -not -path "./.git/*") || true
+          python-version: "3.12"
+          cache: pip
+      - run: pip install ruff>=0.11.0
+      - name: Check formatting
+        run: ruff format --check .
+      - name: Check linting
+        run: ruff check .
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: pip install -r requirements.txt
+      - name: Run tests with coverage
+        run: pytest --cov=app --cov-report=term-missing --cov-report=xml
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+
+  links:
+    name: Check Links
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
       - name: Check links
         uses: lycheeverse/lychee-action@v2
         with:

CITATION.cff

@@ -6,8 +6,8 @@ abstract: "FastAPI backend connecting RootStack database to the OpenStacks front
 authors:
   - family-names: "Sri Raman"
     given-names: "Varna"
-version: 0.2.0
-date-released: "2025-04-28"
+version: 0.3.0
+date-released: "2026-04-04"
 license: MIT
 url: "https://openstacks.dev"
 repository-code: "https://github.com/Varnasr/BridgeStack"

CODE_OF_CONDUCT.md

@@ -0,0 +1,34 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in BridgeStack and the OpenStacks ecosystem a welcoming, inclusive, and harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+**Positive behaviours include:**
+
+- Using welcoming and inclusive language
+- Respecting differing viewpoints and experiences
+- Accepting constructive criticism gracefully
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+**Unacceptable behaviours include:**
+
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Scope
+
+This Code of Conduct applies within all project spaces — issues, pull requests, discussions, and any other channel associated with BridgeStack or OpenStacks.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be reported by contacting the project team at **hello@impactmojo.in**. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contributing to BridgeStack
+
+Thank you for your interest in contributing to BridgeStack! This project is part of the [OpenStacks](https://openstacks.dev) ecosystem, and we welcome contributions of all kinds.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.11+
+- Git
+
+### Setup
+
+```bash
+git clone https://github.com/Varnasr/BridgeStack.git
+cd BridgeStack
+python -m venv .venv
+source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+### Running Locally
+
+```bash
+uvicorn app.main:app --reload
+```
+
+API docs will be at [http://localhost:8000/docs](http://localhost:8000/docs).
+
+### Running Tests
+
+```bash
+pytest                         # run all tests
+pytest --cov=app               # with coverage
+pytest -k "test_geography"     # run specific test class
+```
+
+### Linting & Formatting
+
+```bash
+ruff check .          # check for lint issues
+ruff check --fix .    # auto-fix lint issues
+ruff format .         # format code
+```
+
+## How to Contribute
+
+### Reporting Bugs
+
+Open an issue using the [bug report template](https://github.com/Varnasr/BridgeStack/issues/new?template=bug_report.md). Include:
+
+- Steps to reproduce
+- Expected vs actual behaviour
+- Python version and OS
+
+### Suggesting Features
+
+Open an issue using the [feature request template](https://github.com/Varnasr/BridgeStack/issues/new?template=feature_request.md).
+
+### Submitting Code
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/your-feature`
+3. Make your changes
+4. Run tests and linting:
+   ```bash
+   pytest --cov=app
+   ruff check .
+   ruff format --check .
+   ```
+5. Commit using the [commit conventions](#commit-conventions)
+6. Push and open a pull request
+
+### Commit Conventions
+
+All commit messages must start with one of these prefixes:
+
+| Prefix | Use for |
+|--------|---------|
+| `Add:` | New features or files |
+| `Fix:` | Bug fixes |
+| `Update:` | Enhancements to existing features |
+| `Docs:` | Documentation changes |
+| `Refactor:` | Code restructuring (no behaviour change) |
+| `Test:` | Adding or updating tests |
+| `CI:` | CI/CD pipeline changes |
+| `Chore:` | Maintenance tasks |
+
+Example: `Add: pagination support for indicator values endpoint`
+
+### Pull Request Guidelines
+
+- Keep PRs focused — one feature or fix per PR
+- Include tests for new functionality
+- Update documentation if you change API behaviour
+- Fill in the PR template completely
+
+## Project Structure
+
+```
+app/
+├── core/          # Config, database setup, shared utilities
+├── models/        # SQLAlchemy ORM models
+├── schemas/       # Pydantic request/response schemas
+└── routes/        # FastAPI route handlers
+tests/             # Pytest test suite
+docs/              # Project documentation
+```
+
+## Areas Where Help Is Welcome
+
+- Additional query endpoints and aggregations
+- Pagination and rate limiting
+- Response caching
+- PostgreSQL adapter
+- Test coverage improvements
+- Documentation and examples
+
+## Code of Conduct
+
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
+
+## Questions?
+
+Open a [discussion](https://github.com/Varnasr/BridgeStack/issues) or reach out at hello@impactmojo.in.

Makefile

@@ -0,0 +1,41 @@
+.PHONY: install dev test lint format run docker-up docker-down clean
+
+install:  ## Install production dependencies
+	pip install -r requirements.txt
+
+dev:  ## Install all dependencies (including dev tools)
+	pip install -e ".[dev]"
+
+test:  ## Run tests with coverage
+	pytest --cov=app --cov-report=term-missing
+
+lint:  ## Run linter
+	ruff check .
+
+format:  ## Format code
+	ruff format .
+	ruff check --fix .
+
+check:  ## Run all checks (lint + test)
+	ruff format --check .
+	ruff check .
+	pytest --cov=app
+
+run:  ## Start the development server
+	uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+
+docker-up:  ## Start with Docker Compose
+	docker compose up --build -d
+
+docker-down:  ## Stop Docker Compose
+	docker compose down
+
+clean:  ## Remove build artifacts and caches
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .pytest_cache -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .ruff_cache -exec rm -rf {} + 2>/dev/null || true
+	rm -f .coverage coverage.xml
+	rm -f test.db
+
+help:  ## Show this help
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-15s\033[0m %s\n", $$1, $$2}'