webui-develop/CONTRIBUTING.md

# Contributing to Hermes WebUI

Thanks for contributing.

Hermes WebUI is intentionally simple to work on: Python on the server, vanilla JS in the browser, no build step, no bundler, no frontend framework. The best pull requests preserve that simplicity while solving a real problem cleanly.

## Two Paths to a Strong Pull Request

### Path 1: Small, Focused Changes

This is the fastest path to review and merge.

- Fix one clear bug or add one tightly scoped improvement
- Touch the fewest files you can
- Avoid drive-by refactors mixed into functional changes
- Run the relevant tests locally before opening the PR
- Keep the PR description concise and specific

These are the changes that are easiest to review and safest to merge quickly.

### Path 2: Bigger Changes

If you want to change architecture, reshape a workflow, add a substantial UI feature, or alter core behavior, align on direction first.

- Open an issue, start a discussion, or open a draft PR early
- Explain the problem you are solving, not just the implementation you want
- Call out tradeoffs, migration risk, and any alternatives you considered
- Keep the final PR easy to review by separating unrelated work

Large changes are welcome, but surprise rewrites are hard to review well.

## What We Expect in Every PR

### 1. One Logical Change Per PR

Keep each PR focused. A small related group of fixes is fine. A bug fix plus a CSS cleanup plus a refactor plus a docs rewrite is not.

### 2. Local Verification

Run the test suite locally:

```bash
pytest tests/ -v --timeout=60
```

CI also runs this suite on Python `3.11`, `3.12`, and `3.13`.

If your change affects browser behavior, also run the relevant manual checks from [TESTING.md](TESTING.md).

### 3. Clear PR Description

There is currently no PR template in this repo, so include the important sections yourself:

- Thinking Path
- What Changed
- Why It Matters
- Verification
- Risks / Follow-ups
- Model Used

If the change is user-visible, include screenshots or a short video.

For UI or UX changes, before/after images are required. PRs that change the interface or interaction flow without before/after images will likely be ignored, or closed in a regular maintainer sweep without review.

### 4. AI Usage Disclosure

If AI helped produce the change, say so in the PR description.

Include:

- Provider
- Exact model name or ID
- Any notable mode or tool use that mattered

If no AI was used, write: `None — human-authored`.

### 5. Keep the Docs Honest

If your change alters behavior, architecture, testing, setup, or user-facing workflows, update the relevant docs in the same PR.

Common files:

- [README.md](README.md) for setup, usage, and contributor-facing commands
- [ROADMAP.md](ROADMAP.md) for shipped features and sprint history
- [ARCHITECTURE.md](ARCHITECTURE.md) for implementation details and design constraints
- [TESTING.md](TESTING.md) for manual and automated verification guidance
- [CHANGELOG.md](CHANGELOG.md) when maintainers want release-note-ready entries

## Project-Specific Guidelines

### Preserve the Design Constraints

Hermes WebUI is deliberately:

- No build step
- No bundler
- No frontend framework
- Easy to modify from a terminal

Do not introduce new infrastructure or dependencies unless the gain is clear and the tradeoff is justified.

### Match the Existing Shape of the Codebase

- Server logic belongs in `api/` with `server.py` staying thin
- Frontend behavior belongs in the existing `static/*.js` modules
- Prefer extending current patterns over introducing parallel abstractions
- Keep changes legible to future contributors working directly from the repo in a terminal

### Be Careful With User-Facing Changes

This project is heavily UI-driven. If you change interaction flows, session behavior, workspace browsing, onboarding, or mobile layouts:

- test the happy path
- test reload behavior where relevant
- test narrow/mobile layouts where relevant
- include before/after images in the PR

### Security and Safety Matter

This app can expose workspace contents, run agent actions, and optionally sit behind a reverse proxy or Docker deployment. Treat auth, path handling, uploads, streaming, and environment handling as high-risk areas.

If your PR touches security-sensitive behavior, say so explicitly in the PR description and explain how you verified it.

## Writing a Good PR Message

Start with a short Thinking Path that explains the chain from project goal to the specific fix.

Example:

> - Hermes WebUI aims for near 1:1 parity with the Hermes CLI in a browser
> - Long-running chat turns rely on SSE streaming and session recovery
> - Reloading during an in-flight turn can leave the UI in an inconsistent state
> - The bug was that recovered sessions restored messages but not the live stream state
> - This PR fixes the recovery path so in-flight turns reconnect cleanly after reload
> - The benefit is that users can refresh or reconnect without losing visibility into active work

Another example:

> - Hermes WebUI is intentionally a simple Python + vanilla JS application
> - The right panel is used for workspace browsing and previews
> - On mobile, panel state changes need to be obvious and touch-friendly
> - The existing close affordance was inconsistent with the bottom-nav flow
> - This PR fixes the mobile panel close behavior and aligns it with the current navigation model
> - The result is fewer dead-end UI states on phones

After that, cover:

- what you changed
- why you changed it
- how you verified it
- what risks remain

## Review Tips

Want the smoothest review?

- Keep diffs tight
- Name things clearly
- Avoid unnecessary rewrites
- Add short comments only where the code would otherwise be hard to follow
- Respond directly to review feedback and update the PR description if the scope changes

## Development References

- [README.md](README.md)
- [ARCHITECTURE.md](ARCHITECTURE.md)
- [TESTING.md](TESTING.md)
- [ROADMAP.md](ROADMAP.md)
- [SPRINTS.md](SPRINTS.md)

Questions are best raised early, before a large change is finished.