Merge pull request #2 from sena-labs/claude/nice-dewdney-9a8b8f

docs: align all documentation to WARP-VSC style and template

Author: sena-labs

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,29 +1,43 @@
-## Description
+## Summary
 
 <!-- Brief description of the changes in this PR -->
 
+## Related Issue
+
+<!-- Link to the GitHub issue this PR addresses, e.g.: Closes #42 -->
+
 ## Type of Change
 
 - [ ] Bug fix (non-breaking change that fixes an issue)
 - [ ] New feature (non-breaking change that adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Breaking change (fix or feature that would cause existing functionality to break)
 - [ ] Documentation update
 - [ ] Refactoring (no functional changes)
+- [ ] Test improvement
 
-## Checklist
+## Changes Made
 
-- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines
-- [ ] All tests pass (`python test_pipe.py` — 252/252 ✓)
-- [ ] I have added tests for new functionality (if applicable)
-- [ ] I have updated `CHANGELOG.md` under `[Unreleased]`
-- [ ] I have updated documentation (if applicable)
-- [ ] My code follows the project's code style (PEP 8, type hints)
-- [ ] No secrets, API keys, or credentials are included in this PR
+<!-- List the key changes made in this PR -->
+
+-
+-
+-
 
-## Related Issues
+## Testing
 
-<!-- Link any related issues: Fixes #123, Closes #456 -->
+- [ ] All unit tests pass (`python test_pipe.py` — 252/252 ✓)
+- [ ] New tests added for the changes
+- [ ] Integration tests pass (`python integration_test.py`) — if applicable
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
 
-## Additional Notes
+## Screenshots / Demo
 
-<!-- Any additional context, screenshots, or information -->
+<!-- If applicable, add screenshots or descriptions of manual testing -->
+
+## Checklist
+
+- [ ] My code follows the project's [coding standards](../CONTRIBUTING.md#coding-standards)
+- [ ] I have added docstrings to new public methods
+- [ ] My changes do not introduce debug `print` statements beyond `[OpenRouter Pipe]` logging
+- [ ] No secrets, API keys, or credentials are included in this PR
+- [ ] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to **OpenRouter Pipe** will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
@@ -18,7 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Dead provider-icon code removed** — `info.meta.profile_image_url` was included in model dicts returned by `pipes()` but Open WebUI ignores all fields except `id` and `name`; the field has been removed in favour of the new DB-sync approach
 - **`pipes()` response always closed** — added `finally: response.close()` to guarantee HTTP connections are returned to the session pool in all code paths (auth errors, JSON decode failures, unexpected exceptions)
 
-## [1.2.0] - 2026-02-17
+## [1.2.0] — 2026-02-17
 
 ### Added
 
@@ -57,7 +57,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `_close_think_tag()` helper eliminates duplicated think-tag closure logic (was 5x repeated)
 - `_stream_response` now closes the response in a `finally` block even on consumer `break`
 
-## [1.1.1] - 2026-02-17
+## [1.1.1] — 2026-02-17
 
 ### Changed
 
@@ -73,7 +73,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated SECURITY.md to list v1.1.x as supported
 - Updated `function.json` metadata date
 
-## [1.1.0] - 2026-02-15
+## [1.1.0] — 2026-02-15
 
 ### Added
 
@@ -82,7 +82,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Optional `__event_emitter__` support — shows "Querying OpenRouter..." status in chat UI
 - Additional defensive keys (`metadata`, `files`, `tool_ids`, `session_id`, `message_id`) stripped from payload
 
-## [1.0.0] - 2026-02-14
+## [1.0.0] — 2026-02-14
 
 ### Added
 
@@ -114,7 +114,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Stream parser no longer crashes on malformed JSON chunks
 - HTTP error handler no longer crashes when response body is not JSON
 
-## [0.1.0] - 2026-01-21
+## [0.1.0] — 2026-01-21
 
 ### Added
 

CONTRIBUTING.md

@@ -1,97 +1,169 @@
 # Contributing to OpenRouter Pipe
 
-> **Maintained by [Sena Labs](https://github.com/sena-labs)** · [GitHub](https://github.com/sena-labs/OpenRouter-Pipe)
+Thanks for wanting to contribute! This document is intentionally opinionated: it codifies the
+**deliverable-PR playbook** the maintainers use day-to-day so new contributors can ship changes
+with the same cadence and quality.
 
-Thanks for your interest in contributing.
+## Table of Contents
 
-## Quick Start
+- [Code of Conduct](#code-of-conduct)
+- [Getting started](#getting-started)
+- [Development setup](#development-setup)
+- [Deliverable-PR playbook](#deliverable-pr-playbook)
+- [Commit messages](#commit-messages)
+- [Coding standards](#coding-standards)
+- [Testing](#testing)
+- [Reporting bugs](#reporting-bugs)
+- [Suggesting features](#suggesting-features)
 
-```bash
-git clone https://github.com/sena-labs/OpenRouter-Pipe.git
-cd OpenRouter-Pipe
-python test_pipe.py
-```
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](.github/CODE_OF_CONDUCT.md).
+By participating, you agree to uphold this code.
+
+## Getting started
+
+1. **Fork** the repository on GitHub.
+2. **Clone** your fork locally:
+
+   ```bash
+   git clone https://github.com/<your-username>/OpenRouter-Pipe.git
+   cd OpenRouter-Pipe
+   ```
+
+3. **Install** dependencies:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
 
-## Development
+4. **Verify** the baseline is green before changing anything:
+
+   ```bash
+   python test_pipe.py
+   ```
+
+## Development setup
 
 ### Prerequisites
 
-- Python 3.10+
-- `requests` >= 2.20
-- `pydantic` >= 2.0
+- **Python** ≥ 3.10 (matches the CI matrix).
+- **`requests`** ≥ 2.20.
+- **`pydantic`** ≥ 2.0.
 
-Install dependencies:
+### Useful commands
 
-```bash
-pip install -r requirements.txt
-```
+| Command | Description |
+| --- | --- |
+| `python test_pipe.py` | Run the full unit test suite (252 tests) |
+| `python integration_test.py` | Run live API tests (requires `OPENROUTER_API_KEY`) |
 
-### Running Tests
+## Deliverable-PR playbook
 
-```bash
-python test_pipe.py           # Unit tests (252 tests)
-python integration_test.py    # Live API tests (requires OPENROUTER_API_KEY)
-```
+Every change is shipped as a **single-deliverable pull request**. One PR = one reviewable unit
+of value. The playbook:
+
+1. **Sync `main`** and create a branch with a descriptive slug:
+
+   ```bash
+   git checkout main && git pull
+   git checkout -b feat/<slug>
+   ```
+
+2. **Implement** the smallest complete slice of the change. Prefer surgical edits over
+   incidental refactors.
 
-All unit tests must pass. If adding new functionality, add corresponding tests.
+3. **Add or update tests.** A change without test coverage needs a written justification
+   in the PR body. The unit test suite must remain at 252/252.
 
-### Code Style
+4. **Validate locally** using the same commands CI runs:
 
-- Follow PEP 8 conventions
-- Use type hints for all function signatures
-- Keep methods focused — one responsibility per method
-- Add docstrings for public methods
-- Use `print(f"[OpenRouter Pipe] ...")` for debug logging
+   ```bash
+   python test_pipe.py
+   python integration_test.py   # optional, requires a valid API key
+   ```
 
-## Pull Request Process
+5. **Update `CHANGELOG.md`.** Prepend a bullet under `## [Unreleased]` describing the
+   user-visible impact.
 
-1. **Fork** the repository
-2. Create a **feature branch** (`git checkout -b feature/my-feature`)
-3. Make your changes
-4. **Run the test suite** and ensure all tests pass
-5. Update `CHANGELOG.md` with your changes under `[Unreleased]`
-6. Commit with a clear message (`git commit -m "feat: add XYZ support"`)
-7. Push to your fork and **open a Pull Request**
+6. **Commit with Conventional Commits** (see [Commit messages](#commit-messages)) and push:
+
+   ```bash
+   git push -u origin feat/<slug>
+   ```
+
+7. **Open the pull request** using the [PR template](.github/PULL_REQUEST_TEMPLATE.md) and
+   fill every section.
+
+8. **Verify CI** goes green. A failing test leg blocks the merge — fix forward rather than
+   disabling the check.
+
+Keep the branch focused: if the diff grows beyond ~300 lines of non-generated code, split it.
+
+## Commit messages
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```text
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:** `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `ci`.
+
+**Examples:**
+
+```text
+feat(routing): add PROVIDER_IGNORE valve
+fix(stream): close think tag on mid-stream error
+docs: update README installation steps
+test: add retry exhaustion coverage
+```
 
-### Commit Convention
+## Coding standards
 
-We use [Conventional Commits](https://www.conventionalcommits.org/):
+- **PEP 8** — enforced by convention; keep line length ≤ 100 chars.
+- **Type hints** on every function signature.
+- **One responsibility per method** — keep functions under ~50 lines; extract helpers when they grow.
+- **Docstrings** on every public method using the one-line summary style.
+- **Logging** via `print(f"[OpenRouter Pipe] …")` — never log API keys or user content.
+- No `any`-equivalent type erasure; use proper `dict[str, Any]` annotations.
 
-| Prefix | Usage |
-|--------|-------|
-| `feat:` | New feature |
-| `fix:` | Bug fix |
-| `docs:` | Documentation only |
-| `refactor:` | Code restructuring |
-| `test:` | Adding or updating tests |
-| `chore:` | Maintenance tasks |
+## Testing
 
-### PR Checklist
+- **Framework:** Python `unittest` (stdlib).
+- **Mock strategy:** `unittest.mock.patch` for HTTP calls and Open WebUI internals.
+- **Conventions:**
+  - Test path mirrors source: `openrouter_pipe.py` ↔ `test_pipe.py`.
+  - Each test class covers one unit (`TestPreparePayload`, `TestStreamResponse`, etc.).
+  - Use descriptive method names: `test_fallback_deduplication_removes_duplicates`.
+- **Run the suite the same way CI does:** `python test_pipe.py`. Integration tests require a
+  live API key and are optional for most contributions.
 
-- [ ] Tests pass (`python test_pipe.py` and `python integration_test.py` → 0 failures)
-- [ ] New features have corresponding tests
-- [ ] `CHANGELOG.md` updated
-- [ ] Code follows existing style conventions
-- [ ] No OpenRouter API keys or secrets committed
+## Reporting bugs
 
-## Reporting Issues
+When reporting a bug, open a [GitHub issue](https://github.com/sena-labs/OpenRouter-Pipe/issues)
+using the **Bug report** template and include:
 
-When reporting a bug, please include:
+1. **Open WebUI version** (`Admin Panel → About`).
+2. **Python version** (`python --version`).
+3. **Steps to reproduce** the issue.
+4. **Expected vs. actual behavior.**
+5. **Error logs** — check the Open WebUI server logs and filter for `[OpenRouter Pipe]` messages.
 
-1. **Open WebUI version** you're running
-2. **Python version** (`python --version`)
-3. **Steps to reproduce** the issue
-4. **Expected vs actual behavior**
-5. **Error logs** (check Open WebUI server logs for `[OpenRouter Pipe]` messages)
+**Do not** include your API key in the issue. Redact it before pasting logs.
 
-## Feature Requests
+## Suggesting features
 
-Before requesting a feature:
+Before opening a feature request:
 
-1. Check [OpenRouter API docs](https://openrouter.ai/docs) to confirm the feature exists upstream
-2. Check [Open WebUI Pipe docs](https://docs.openwebui.com/features/plugin/functions/pipe) for compatibility
-3. Open an issue describing the feature and its use case
+1. Check the [OpenRouter API docs](https://openrouter.ai/docs) to confirm the feature exists upstream.
+2. Check the [Open WebUI Pipe docs](https://docs.openwebui.com/features/plugin/functions/pipe) for compatibility constraints.
+3. Open an issue using the **Feature request** template and describe the use case and expected behavior.
 
-## License
+---
 
-By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
+Thanks for helping improve OpenRouter Pipe! 🚀