diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..04e7b7b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,33 @@ +## Description + + + +## Type of Change + +- [ ] Bug fix +- [ ] Feature or enhancement +- [ ] Documentation +- [ ] Session logic +- [ ] CLI +- [ ] Settings or configuration +- [ ] Tests or CI + +## Validation + +- [ ] The scope matches the linked issue and contains no unrelated changes. +- [ ] Tests were added or updated for behavior changes. +- [ ] The relevant tests and full `pytest` suite pass locally. +- [ ] The CI-blocking Flake8 checks pass locally. +- [ ] `CHANGELOG.md` was updated under `[Unreleased]` for user-visible changes, or is not applicable. +- [ ] `rooms.settings.example.yaml` was updated for settings schema changes, or is not applicable. +- [ ] User-facing documentation was updated where needed. + +## Test Results + + + +## Related Issues + + + +Fixes # diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5cc45c4..e32f599 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,59 +4,143 @@ # Contributing to Rooms -
+Thank you for helping improve Rooms. This guide is the entry point for code, CLI, settings, documentation, and test contributions. Rooms is local-first: changes should preserve user privacy, predictable orchestration, and offline-friendly testing. -Thank you for your interest in contributing to Rooms. We welcome contributions from the community to help make this framework even better for local-first multi-agent orchestration. +## Navigation -**Documentation:** see the [docs hub](docs/README.md) for architecture, settings, examples, and testing guides. +| Section | Purpose | +| :--- | :--- | +| [Ways to contribute](#ways-to-contribute) | Choose the right scope and verification path | +| [Getting started](#getting-started) | Fork, sync, branch, and install | +| [Universal expectations](#universal-expectations) | Follow project-wide contribution standards | +| [Pull request process](#pull-request-process) | Prepare a reviewable PR | +| [Related documents](#related-documents) | Find architecture, testing, and configuration references | ---- +## Ways to contribute -## How to Contribute +Start from an approved or assigned issue when possible. For larger behavior or architecture changes, discuss the approach with maintainers before implementation. -### Reporting Bugs -Use the Bug Report template to describe the issue. Provide clear steps to reproduce the bug and include information about your environment (OS, Python version, Local LLM provider). +Use the GitHub [Bug Report](https://github.com/ARPAHLS/rooms/issues/new?template=bug_report.yml) or [Feature Request](https://github.com/ARPAHLS/rooms/issues/new?template=feature_request.yml) template when opening new work. -### Suggesting Enhancements -Use the Feature Request template. Explain the motivation behind the suggestion and how it benefits the framework. +| Type | Typical paths | Labels | Verify locally | +| :--- | :--- | :--- | :--- | +| Core framework | `rooms/agent.py`, `rooms/session.py`, `rooms/config.py` | `enhancement`, `session-logic` | Relevant unit tests plus the full suite | +| CLI wizard | `cli.py`, `rooms/skills_cli.py` | `cli` | `tests/test_cli.py`, CLI settings smoke tests | +| Settings | `rooms/settings.py`, `rooms.settings.example.yaml` | `enhancement`, `cli` | `tests/test_settings.py`, `tests/test_cli_settings_smoke.py` | +| Documentation | `README.md`, `docs/`, `CONTRIBUTING.md` | `documentation` | Run `pytest tests/test_docs_hub.py -q` | +| Tests | `tests/test_*.py` | `testing` | Run the changed test and the full suite | +| Bug fix | Paths identified by the issue | `bug` | Add a regression test that fails before the fix | +| Good first issue | Usually focused docs, tests, or small fixes | `good first issue` | Follow the verification path for the underlying type | -### Pull Requests -1. **Fork the Repository**: Create your own branch from `main`. -2. **Implement Changes**: Follow the project's coding style and naming conventions. -3. **Run Tests**: Ensure all existing tests pass by running: - ```bash - $env:PYTHONPATH="."; python -m pytest tests/ -v - ``` -4. **Add Tests**: If you are adding new logic, please include corresponding tests in `tests/test_session.py`. -5. **Submit PR**: Provide a clear description of what the PR changes and why. -6. **Update Changelog**: Please note that a project changelog exists at `CHANGELOG.md`. Contributors will be requested to update the `[Unreleased]` section of the changelog once official versioned releases begin. ---- +## Getting started + +### 1. Fork and clone + +Fork [ARPAHLS/rooms](https://github.com/ARPAHLS/rooms), then clone your fork and register the upstream repository: + +```bash +git clone https://github.com//rooms.git +cd rooms +git remote add upstream https://github.com/ARPAHLS/rooms.git +``` + +### 2. Sync and branch + +Create every branch from the latest upstream `main`: + +```bash +git fetch upstream +git checkout main +git pull --ff-only upstream main +git checkout -b feat/issue-47-short-description +``` + +Use `/issue--`, with a focused prefix such as `feat`, `fix`, `docs`, or `test`. Do not work directly on `main`. + +### 3. Install dependencies + +Rooms targets Python 3.13. Create a virtual environment, then install runtime and contributor tools: + +```bash +python -m venv venv +source venv/bin/activate # Windows: venv\Scripts\activate +python -m pip install -r requirements.txt pytest flake8 +``` + +## Universal expectations + +### Scope and style + +- Keep the diff limited to the issue's acceptance criteria; avoid unrelated refactors. +- Match existing Python, Markdown, Pydantic, and CLI patterns in nearby files. +- Add or update documentation when behavior, settings, or commands change. +- Keep inference tests deterministic. Mock LiteLLM, Ollama, filesystem, and Skillware boundaries rather than calling live services. +- Never commit API keys, `.env`, or `rooms.settings.yaml`. Credentials belong in the environment; see [Settings & preflight](docs/SETTINGS.md). + +### Design principles + +- **Local-first:** Prefer private, offline-capable workflows and local inference where practical. +- **Zero-leakage:** Do not send user data or credentials to third parties without explicit configuration. +- **Aesthetic CLI:** Keep terminal output clear, consistent, and polished when changing user-facing flows. + +### Changelog policy + +Update the `[Unreleased]` section of [CHANGELOG.md](CHANGELOG.md) when a PR changes user-visible behavior, configuration, CLI output, or documented workflows users rely on. Use the existing `Added`, `Changed`, or `Fixed` headings. Tests, internal refactors, and minor wording fixes usually do not need an entry. Do not create a release version heading unless a maintainer requests it. + +### Tests and CI + +Run the full suite and the CI-blocking Flake8 checks before opening a PR: + +```bash +PYTHONPATH=. python -m pytest tests/test_docs_hub.py -q # documentation link checks +PYTHONPATH=. python -m pytest tests/ -v +python -m flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics +``` + +See [Testing Strategy](docs/TESTING.md) for focused commands and mocking examples. GitHub Actions repeats lint and test checks on pull requests. + +### Git authorship + +Use an email verified on your GitHub account so commits are attributed correctly. Check before committing: -## Design Philosophy +```bash +git config user.name +git config user.email +``` -**Local-First** -Always favor solutions that respect user privacy and offline execution. +If needed, set a verified email with `git config user.email "you@example.com"`. GitHub's private `noreply` address is also acceptable when enabled in your [email settings](https://github.com/settings/emails). -**Aesthetic Excellence** -All CLI and documentation updates should prioritize a premium, modern feel. +## Pull request process -**Zero-Leakage** -Be cautious with third-party integrations that might leak data. +1. Link the assigned or approved issue using `Fixes #123` or `Refs #123`. +2. Implement only the requested scope and add tests for behavior changes. +3. Update `rooms.settings.example.yaml` when the supported settings schema changes. +4. Update `[Unreleased]` when required by the changelog policy above. +5. Run focused tests, the full test suite, and Flake8 locally. +6. Commit with a short imperative subject such as `fix: handle empty persona list` or `docs: clarify settings precedence`. +7. Push the branch to your fork and open a PR against `ARPAHLS/rooms` `main` using the [PR template](.github/PULL_REQUEST_TEMPLATE.md). +8. Ensure CI passes and address review feedback on the same branch. -## Automated Checks -Every push and Pull Request is automatically verified by our GitHub Actions CI/CD pipeline, which runs: -- **Style Checks**: Code formatting and linting via `flake8`. -- **Logic Verification**: Full suite of `pytest` unit tests for turn orchestration, expertise scoring, and session memory. +PR descriptions should explain what changed, why it changed, and how it was verified. Include screenshots only when terminal output or another visible workflow changes. -Ensure your changes pass locally before submitting to maintain the build status. +## Related documents -## Project Roadmap -Check our [GitHub Issues](https://github.com/arpahls/Rooms/issues) to see what we are currently working on. +| Document | Purpose | +| :--- | :--- | +| [Architecture](docs/ARCHITECTURE.md) | LiteLLM routing, sessions, orchestration, and storage | +| [Examples](docs/EXAMPLES.md) | Scenario and parameter guidance | +| [Settings & preflight](docs/SETTINGS.md) | YAML, environment variables, and Ollama checks | +| [Testing Strategy](docs/TESTING.md) | Pytest scope, commands, and mocking patterns | +| [Documentation hub](docs/README.md) | Index of all project guides | +| [Agent contribution workflow (planned)](https://github.com/ARPAHLS/rooms/issues/48) | Tracks the dedicated workflow guide for contributing agents | +| [Changelog](CHANGELOG.md) | Current `[Unreleased]` changes | +| [Pull request template](.github/PULL_REQUEST_TEMPLATE.md) | Required PR summary and checklist | +| [GitHub Issues](https://github.com/ARPAHLS/rooms/issues) | Open work and issue templates | ---
ARPA Logo
- Developed and Maintained by ARPA HELLENIC LOGICAL SYSTEMS + Developed and maintained by ARPA HELLENIC LOGICAL SYSTEMS
diff --git a/README.md b/README.md index 2d26b17..db7a325 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ The framework allows extreme granularity in handling session configurations: | [Examples & best practices](docs/EXAMPLES.md) | Parameter cheat sheet, personas, scenarios, edge cases | | [Skillware integration](docs/SKILLWARE.md) | Skills CLI, wizard assignment, runtime behavior | | [Testing](docs/TESTING.md) | Pytest, mocking, CI smoke tests | -| [Contributing](CONTRIBUTING.md) | Bugs, PRs, design philosophy | +| [Contributing](CONTRIBUTING.md) | Contribution types, fork workflow, local checks, and PR process | | [Changelog](CHANGELOG.md) | Notable updates | ## Project Structure diff --git a/docs/README.md b/docs/README.md index 312e6ee..2a2c80a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -22,7 +22,8 @@ Welcome to the Rooms documentation hub. Start here to find the right guide by au | Topic | Location | |-------|----------| -| Contributing, design philosophy, PR workflow | [CONTRIBUTING.md](../CONTRIBUTING.md) | +| Contribution types, fork setup, local checks, and PR workflow | [CONTRIBUTING.md](../CONTRIBUTING.md) | +| Pull request description and review checklist | [Pull request template](../.github/PULL_REQUEST_TEMPLATE.md) | | Notable changes | [CHANGELOG.md](../CHANGELOG.md) | | Roadmap and open work | [GitHub Issues](https://github.com/arpahls/Rooms/issues) |