release: consolidate core refactors, security fixes, documentation overhaul, and CI/CD pipelines

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug Report
+about: Create a report to help us improve ZCore
+title: 'bug: '
+labels: bug
+assignees: ''
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Steps to reproduce:
+2. Code snippet or minimal reproducible example (highly recommended):
+```python
+# Paste your minimal code here
+```
+3. Run command '...'
+4. See error/traceback.
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Traceback / Logs**
+If applicable, paste your structured logs or console tracebacks here:
+```text
+# Paste raw logs or tracebacks here
+```
+
+**Environment (please complete the following information):**
+- Python Version: [e.g. 3.11]
+- FastAPI Version: [e.g. 0.110.0]
+- ZCore Version: [e.g. 0.1.0-beta.5]
+- SQLAlchemy Version: [e.g. 2.0.28] (if applicable)
+- Database Engine: [e.g. SQLite (aiosqlite) / PostgreSQL (asyncpg)]
+- Redis Version: [e.g. 5.0.3] (if using cache or streams)

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature Request
+about: Suggest an idea or enhancement for ZCore
+title: 'feat: '
+labels: enhancement
+assignees: ''
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is (e.g. "I'm frustrated when trying to run...")
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen. How should the API look or behave under ZCore?
+
+**How does this align with ZCore's Design Principles?**
+Please explain how this feature complements FastAPI without hiding its core features, and how it fits into ZCore's modular philosophy.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context, code blocks, or references about the feature request here.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+## Description
+
+Please include a summary of the change and which issue is fixed. Please also include relevant motivation and context.
+
+Fixes # (issue number)
+
+## Type of change
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Refactoring (architectural or code cleanup with no functional changes)
+- [ ] Documentation update
+
+## How Has This Been Tested?
+
+Please describe the tests that you ran to verify your changes.
+
+- [ ] Unit/Integration tests (`hatch run test`)
+- [ ] Static type check passing (`mypy src/`)
+
+## Checklist:
+
+- [ ] My code follows the style guidelines and architectural rules of this project
+- [ ] I have performed a self-review of my own code
+- [ ] My changes pass strict static type analysis (`mypy src/` generates no warnings)
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation (under `docs/`)
+- [ ] My changes generate no new runtime warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works

.github/release.yml

@@ -0,0 +1,29 @@
+changelog:
+  exclude:
+    labels:
+      - ignore
+    authors:
+      - dependabot[bot]
+  categories:
+    - title: 'Features 🚀'
+      labels:
+        - enhancement
+        - feat
+        - backend
+    - title: 'Bug Fixes 🐛'
+      labels:
+        - bug
+        - fix
+    - title: 'Refactoring & Architecture 🛠️'
+      labels:
+        - refactor
+        - security
+        - di
+        - database
+    - title: 'Documentation 📝'
+      labels:
+        - documentation
+        - docs
+    - title: 'Dependencies & Maintenance ⚙️'
+      labels:
+        - dependencies

.github/workflows/test.yml

@@ -0,0 +1,35 @@
+name: Test Suite (CI)
+
+on:
+  pull_request:
+    branches:
+      - master
+      - develop
+  push:
+    branches:
+      - master
+      - develop
+
+jobs:
+  test:
+    name: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: Upgrade pip
+        run: python -m pip install --upgrade pip
+
+      - name: Install Hatch and Ruff
+        run: pip install hatch ruff
+
+      - name: Run Ruff Lint Check
+        run: ruff check src/zcore
+
+      - name: Run Hatch Tests
+        run: hatch test

CONTRIBUTING.md

@@ -0,0 +1,167 @@
+# Contributing to ZCore
+
+First, thank you for considering contributing to ZCore! It is through developers like you that we can continue to refine this architectural chassis for FastAPI.
+
+Please take a moment to review this document to ensure your contributions align with our design philosophy, codebase standards, and development workflows.
+
+---
+
+## 🏛️ Our Design Principles
+
+When proposing changes or writing code for ZCore, please keep these core pillars in mind:
+1. **The Complementary Promise:** ZCore must never obscure or lock developers out of native FastAPI/Pydantic capabilities. Your contributions should enhance, not restrict, developer freedom.
+2. **Strict Typings:** ZCore is designed with highly strict type safety. All public APIs must be fully annotated and pass static analysis checks without warnings.
+3. **Fail-Safe Security:** Security defaults (like magic byte verification or secure fallback JWT checks) should be enforced out-of-the-box, protecting developers from accidental vulnerabilities.
+4. **Performance Pragmatism:** Performance over-optimization is a trap, but unnecessary overhead (like repetitive reflection without caching) must be avoided.
+
+### ⛔ What We Don't Accept
+To preserve ZCore's lightweight, explicit, and highly predictable nature, we generally avoid:
+- **Tight Coupling:** Features that tightly bind ZCore to FastAPI internals or prevent independent unit testing of core components.
+- **Implicit "Magic" Behavior:** We prefer explicit, clear configuration over automatic, hard-to-debug "magic" conventions.
+- **Breaking Changes:** Any breaking changes submitted without a clearly documented and seamless migration path.
+- **Heavy Runtime Overhead:** Third-party dependencies or features that introduce unnecessary CPU/memory overhead (e.g., repetitive reflection without proper caching layers).
+
+---
+
+## 🚦 Before You Contribute
+
+To help us maintain a high-quality codebase and manage our maintainer overhead, please follow these steps before opening an issue or a pull request:
+
+1. **Search Existing Issues:** Ensure the bug or feature request has not already been reported or discussed.
+2. **Provide a Minimal Reproducible Example (MRE):** When reporting bugs, please provide a self-contained, copy-pasteable script that reproduces the issue. Issues without a reproduction case may be closed.
+3. **Include Environment Information:** Always specify your Python, FastAPI, and ZCore versions, as well as your operating system.
+
+---
+
+## 🛠️ Local Development Setup
+
+ZCore utilizes **Hatch** as its build backend and project manager. Follow these steps to prepare your local development environment:
+
+### 1. Fork and Clone
+Fork the repository on GitHub, then clone your fork locally:
+```bash
+git clone https://github.com/your-username/zcore.git
+cd zcore
+```
+
+### 2. Install Development Dependencies
+It is highly recommended to use a virtual environment. Install ZCore in editable mode along with all optional and development dependencies:
+```bash
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install with editable mode and all dev extras
+pip install -e ".[all,dev]"
+```
+
+---
+
+## 🧪 Testing Guidelines
+
+We aim for high test coverage on core architectural units. ZCore uses `pytest` and `pytest-asyncio` for asynchronous test suites.
+
+### Test Architecture
+ZCore's codebase is highly modular. To ensure that components like the Kernel, Plugins, Dependency Injection (DI), Unit of Work (UOW), Router, and Middleware interact correctly, we organize our tests as follows:
+
+```text
+tests/
+├── unit/                # Tests for isolated, single architectural units with mocks
+│   ├── test_repository.py
+│   └── test_zchema.py
+├── integration/         # Tests verifying interactions between modules
+│   ├── test_kernel_startup.py
+│   ├── test_plugin_loading.py
+│   └── test_request_scope.py
+└── e2e/                 # Full end-to-end request/response flows using TestClient
+    └── test_crud_flow.py
+```
+
+### Running Tests Locally
+Run the standard pytest suite using:
+```bash
+pytest
+```
+
+If you prefer to run tests inside Hatch-isolated environments:
+```bash
+hatch run test
+```
+
+### Writing Tests
+- **Asynchronous Tests:** Ensure your async tests are decorated with `@pytest.mark.asyncio`.
+- **Isolation:** Tests should not leave behind lingering SQLite databases, active sessions, or running background threads.
+- **Mocks:** When writing tests that require external services like Redis, implement mock fallbacks where appropriate to ensure the test suite can run fully offline.
+
+---
+
+## 🔍 Code Quality & Static Analysis
+
+Before submitting a Pull Request, your code must satisfy strict formatting, linting, and type-checking constraints.
+
+### 1. Type Checking
+ZCore enforces strict type checks via `mypy`. To verify your changes conform to the strict rules defined in `pyproject.toml`, run:
+```bash
+mypy src/
+```
+
+### 2. Linting & Formatting
+Ensure your code is clean, PEP-8 compliant, and structured consistently. We recommend using `ruff` for formatting and linting:
+```bash
+ruff check src/
+ruff format src/
+```
+
+---
+
+## 📝 Commit Message Conventions
+
+ZCore uses the **Conventional Commits** specification to automate our changelog generation and semantic versioning. Your commit messages must follow this structure:
+
+```text
+<type>(<scope>): <description>
+```
+
+Common types include:
+- `feat`: A new feature (corresponds to a minor version bump).
+- `fix`: A bug fix (corresponds to a patch version bump).
+- `docs`: Documentation updates.
+- `refactor`: Code changes that neither fix a bug nor add a feature.
+- `test`: Adding or correcting tests.
+- `ci`: Changes to our CI/CD workflows or scripts.
+
+*Examples:*
+- `feat(di): add redis plugin support`
+- `fix(uow): resolve transaction rollback issue on async commit`
+- `docs(zchema): update guide for dynamic schema pruning`
+
+---
+
+## 🚀 Pull Request Process
+
+We appreciate atomic, focused Pull Requests. To increase the chances of your PR being merged quickly, please follow this process:
+
+```mermaid
+flowchart LR
+    A[Create Feature Branch] --> B[Write Code & Tests]
+    B --> C[Pass Mypy & Pytest]
+    C --> D[Update Docs if needed]
+    D --> E[Submit PR]
+```
+
+1. **Branch Naming:** Use descriptive branch names (e.g., `feature/add-s3-provider` or `bugfix/fix-uow-flush`).
+2. **Atomic Commits:** Keep your commits focused on single logical changes and adhere to the conventional commits schema.
+3. **Documentation:** If you are adding a new feature or modifying an existing protocol, you **must** update the corresponding documentation page under the `docs/` folder.
+
+### 🛡️ CI/CD & Branch Protection
+Our repository has strict branch protection rules configured on `master` and `develop`.
+- **Mandatory CI Checks:** Your Pull Request cannot be merged unless all status checks (Linting with Ruff, Type-checking with Mypy, and Test Suites with Pytest) pass successfully in our GitHub Actions pipeline.
+- **No Direct Pushes:** All code changes must go through a Pull Request. Direct pushes to protected branches are blocked.
+
+---
+
+## 📄 Licensing & Copyright
+
+By contributing to ZCore, you agree that your contributions will be licensed under the project's **Apache License 2.0**.
+
+- **No CLA Required:** We do not currently require a signed Contributor License Agreement (CLA) for individual contributions.
+- **Certificate of Origin:** By submitting a Pull Request, you assert that you have the right to submit this code and that it conforms to an open-source contribution under the Apache 2.0 terms.