diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 000000000..ace54f587 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,121 @@ +name: Bug report +description: Something is broken or doesn't behave the way it should. +title: "bug: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Before opening, please: + + - search existing issues for the same symptom + - try to reproduce on the latest version + - if it's a UI bug, capture a screenshot or short video. text descriptions of UI bugs almost always lose detail. + + - type: textarea + id: description + attributes: + label: What's broken + description: What happened, and what did you expect to happen instead? + placeholder: | + I tried to X, expected Y, got Z. + validations: + required: true + + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: The shortest sequence that triggers the bug. If you can't reproduce on demand, say so. + placeholder: | + 1. Open the desktop app + 2. Pair a daemon + 3. Click X + 4. ... + validations: + required: true + + - type: dropdown + id: surface + attributes: + label: Where did this happen + description: The surface you saw the bug on. Pick the closest match. + options: + - iOS app + - Android app + - Web (browser) + - Desktop (Electron) + - CLI + - Daemon + - Other + validations: + required: true + + - type: input + id: paseo-version + attributes: + label: Paseo version + description: Settings → About in the app, or `paseo --version` from the CLI. + placeholder: "0.1.71" + validations: + required: true + + - type: input + id: os-version + attributes: + label: OS version + description: Only relevant for desktop, CLI, or daemon issues. Skip for mobile or web. + placeholder: "macOS 15.2, Windows 11, Ubuntu 24.04" + + - type: dropdown + id: provider + attributes: + label: Agent provider + description: If the bug involves a specific agent provider, pick which one. + options: + - Not relevant + - Claude Code + - Codex + - OpenCode + - Custom provider + + - type: textarea + id: provider-details + attributes: + label: Provider configuration + description: | + If the bug involves an agent, what version are you on and what API are you using? Provider behavior changes a lot across versions and API backends. + placeholder: | + Claude Code v1.2.3 with Anthropic API + Codex CLI v0.5.0 with OpenAI API + OpenCode v0.3.1 + (or paste the relevant section of ~/.paseo/config.json for custom providers) + + - type: textarea + id: logs + attributes: + label: Logs + description: | + Paste relevant log output. Strongly preferred for crashes and daemon issues. + + - **Daemon log:** `~/.paseo/daemon.log` (override with `$PASEO_HOME`) + - **Electron log (macOS):** `~/Library/Logs/Paseo/main.log` + - **Electron log (Windows):** `%APPDATA%\Paseo\logs\main.log` + - **Electron log (Linux):** `~/.config/Paseo/logs/main.log` + + Paste the **full log around the time of the bug**, not a summary. If you used an AI to investigate, paste the raw log it read, not the AI's interpretation. AI summaries skew the signal and waste my time. + render: text + + - type: textarea + id: screenshots + attributes: + label: Screenshots or video + description: | + **Required for UI bugs.** Drag and drop directly into this field. Short videos beat screenshots for anything involving interaction or animation. + + - type: markdown + attributes: + value: | + --- + + **A note on AI-assisted reports.** Using an agent to gather information (logs, repro steps, version checks) is fine and useful. Using an agent to *diagnose* the bug and then submitting only that diagnosis is not. Agents routinely correlate adjacent log lines as cause-and-effect when they aren't related, and once a report is filtered through an AI summary I lose the signal I need to actually fix the bug. Paste the raw inputs. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..fc9435c8a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Discord + url: https://discord.gg/jz8T2uahpH + about: Quick questions, sharing a video of a bug, or anything that's better as a chat. A lot of issues start better here. diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml new file mode 100644 index 000000000..cc08d17bc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -0,0 +1,43 @@ +name: Feature request +description: Propose a new feature or a change to existing behavior. +title: "feat: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Paseo is opinionated and maintained by one person. Feature requests are welcome, but they get evaluated against product fit, not just usefulness, and the bar is whether the change keeps the product lean enough for one person to maintain. + + Big ideas are better discussed in [Discord](https://discord.gg/jz8T2uahpH) first. And please don't open a feature request and a PR at the same time, get alignment on the idea before writing code. + + - type: checkboxes + id: prior-search + attributes: + label: Prior search + options: + - label: I searched existing issues and discussions, and this isn't already proposed. + required: true + + - type: textarea + id: problem + attributes: + label: What's the problem + description: What are you actually trying to do, and why is the current behavior in the way? + placeholder: | + When I'm doing X, I want to Y, but Paseo currently Z. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: What would solve it + description: A rough sketch of the change. Mockups, screenshots from other apps, or a short video are very welcome, especially for UI proposals. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives you considered + description: Optional. What else did you try, and why doesn't it work? diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..7d5039aed --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,43 @@ + + +### Linked issue + +Closes # + + + +### Type of change + +- [ ] Bug fix +- [ ] New feature (with prior issue + design alignment) +- [ ] Refactor / code improvement +- [ ] Docs + +### What does this PR do + + + +### How did you verify it + + + +### Checklist + +- [ ] One focused change. Unrelated cleanups split out. +- [ ] `npm run typecheck` passes +- [ ] `npm run lint` passes +- [ ] `npm run format` ran (Biome) +- [ ] UI changes include screenshots or video for every affected platform +- [ ] Tests added or updated where it made sense diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 29bcd6618..553836b17 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,31 +1,24 @@ # Contributing to Paseo -Thanks for taking the time to contribute. - ## How this project works -Paseo is a BDFL project. Product direction, scope, and what ships are the maintainer's call. +Paseo is opinionated and maintained by one person. I read every issue and PR myself, so review cost is real. -This means: +- **Feature requests are welcome.** Open an issue describing the problem. Get a thumbs up before writing code. Big ideas are better discussed in [Discord](https://discord.gg/jz8T2uahpH) first. +- **Objective bug fixes don't need a prior issue.** Reference what's broken, keep the diff narrow, open the PR. +- **The product stays lean.** I'll close, scope down, or rewrite PRs that add surface area I don't want to maintain, even if the code is fine. -- PRs submitted without prior discussion will likely be rejected, heavily modified, or scoped down. -- The maintainer may rewrite, split, cherry-pick from, or close any PR at their discretion. -- There is no obligation to merge a PR as-submitted, regardless of code quality. +## Reporting bugs -This is not meant to discourage contributions. It is meant to set clear expectations so nobody wastes their time. +Fill in the bug report form. The fields are there because asking back for the surface, version, provider config, and logs is where most of my time on a bad report goes. -## How to contribute - -1. **Open an issue first.** Describe the problem or improvement. Get a thumbs up before writing code. -2. **Keep it small.** One bug, one flow, one focused change. -3. **Open a PR** once there is alignment on scope. - -If you want to propose a direction change, start a conversation. +- **Full logs, not AI summaries.** Use an agent to grab the relevant log section if you want, but paste the raw log. Agents routinely correlate adjacent lines as cause-and-effect when they aren't, and once a report is filtered through that the signal I need is gone. +- **Agents for information gathering, not diagnosis.** A bot that grabs your daemon log, version, and OS is helpful. A bot that submits its own theory of the bug is noise 99% of the time. +- **Screenshots or video for UI bugs.** A 10-second recording beats a paragraph. +- **One bug per issue.** Three findings, three issues. ## Before you start -Please read these first: - - [README.md](README.md) - [docs/architecture.md](docs/architecture.md) - [docs/development.md](docs/development.md) @@ -35,134 +28,36 @@ Please read these first: ## What is most helpful -The most useful contributions right now are: - -- bug fixes -- windows and linux specific fixes +- bug fixes (especially Windows and Linux) - regression fixes - doc improvements -- packaging / platform fixes -- focused UX improvements that fit the existing product direction +- packaging and platform fixes +- focused UX improvements that fit the product direction - tests that lock down important behavior -## Scope expectations - -Please keep PRs narrow. - -Good: - -- fix one bug -- improve one flow -- add one focused panel or command -- tighten one piece of UI - -Bad: - -- combine multiple product ideas in one PR -- bundle unrelated refactors with a feature -- sneak in roadmap decisions - -If a contribution contains multiple ideas, split it up. - -## Product fit matters - -Paseo is an opinionated product. - -When reviewing contributions, the bar is not just: - -- is this useful? -- is this well implemented? - -It is also: - -- does this fit Paseo? -- does this add product surface that will be hard to maintain? -- does the value justify the maintenance surface it adds? -- does this solve a common need or over-serve an edge case? -- does this preserve the product's current direction? - ## Development setup -### Prerequisites - -- Node.js matching `.tool-versions` -- npm workspaces - -### Start local development - -```bash -# runs both daemon and expo app -npm run dev -``` - -Useful commands: - ```bash +npm run dev # daemon + expo npm run dev:server npm run dev:app npm run dev:desktop npm run dev:website -npm run cli -- ls -a -g ``` -Read [docs/development.md](docs/development.md) for build-sync gotchas, local state, ports, and daemon details. +[docs/development.md](docs/development.md) covers build sync, local state, and ports. Coding rules live in [docs/coding-standards.md](docs/coding-standards.md). -## Multi-platform testing +## Pull requests -Paseo ships to mobile (iOS/Android), web, and desktop (Electron). Every UI change must be tested on mobile and web at minimum, and desktop if relevant. Things that look fine on one surface regularly break on another. +- One focused change per PR. Split unrelated cleanups out. +- Reference the issue you're fixing, unless it's a small objective bug. +- UI changes need screenshots or video on every affected platform (mobile, web, desktop). Things that look fine on one surface regularly break on another. +- `npm run typecheck` and `npm run lint` must pass. +- Don't make breaking WebSocket or protocol changes. Old apps and old daemons coexist in the wild. +- The PR template applies whether you used the web UI or `gh pr create`. Don't strip it out. -Common checks: - -```bash -npm run typecheck -npm run test --workspaces --if-present -``` - -Important rules: - -- always run `npm run typecheck` after changes -- tests should be deterministic -- prefer real dependencies over mocks when possible -- do not make breaking WebSocket / protocol changes -- app and daemon versions in the wild lag each other, so compatibility matters - -If you touch protocol or shared client/server behavior, read the compatibility notes in [CLAUDE.md](CLAUDE.md). - -## Coding standards - -Paseo has explicit standards. Follow them. - -The full guide lives in [docs/coding-standards.md](docs/coding-standards.md). - -## PR checklist - -Before opening a PR, make sure: - -- there was prior discussion and alignment on scope (issue or conversation) -- the change is focused, one idea per PR -- the PR description explains what changed and why -- **UI changes include screenshots or videos** for every affected platform (mobile, web, desktop) -- UI changes have been tested on mobile and web at minimum -- typecheck passes -- tests pass, or you clearly explain what could not be run -- relevant docs were updated if needed - -## Communication - -If you are unsure whether something fits, ask first. - -That is especially true for: - -- new core UX -- naming / terminology changes -- new extension points -- new orchestration models -- anything that would be hard to remove later - -Early alignment saves everyone time. +**On AI-assisted PRs.** AI in the loop is fine. The bar is whether _you_ tested the change and can explain why it works. A confident wall of AI prose with no evidence of testing is a red flag and usually gets closed. If you don't fully understand why your fix works, say so directly. "Here's the repro before and after, not sure why this fixes it" is much better than a fabricated explanation. ## Forks are fine -If you want to explore a different product direction, a fork is completely fine. - -Paseo is open source on purpose. Not every idea needs to land in the main repo to be valuable. +If you want to explore a different product direction, fork. Paseo is open source on purpose. Not every idea needs to land here to be valuable.