Skip to content

DOC: Add Windows troubleshooting & clarify User vs Developer setup #927

@skyforge-glitch

Description

@skyforge-glitch

What's wrong with the existing documentation

Problem

Several contributors on Windows (including me) ran into confusion while setting up PictoPy locally:

  • The Windows .exe build works, but
  • The Tauri dev flow often fails (backend startup / logging recursion / server readiness)
  • Backend runs fine when started standalone (fastapi dev)
  • Frontend/Tauri assumes backend auto-start, which is not always true on Windows

This makes it unclear:

  • how users vs contributors are expected to run PictoPy
  • whether Windows is fully supported for development or only for packaged builds

Proposal

Add a Windows-specific section to CONTRIBUTING.md (or a new doc) that clearly explains:

  1. User workflow (recommended for Windows users)

    • Download .exe
    • First run may fail → grant firewall permission → reopen
    • App works after that
  2. Developer workflow on Windows

    • Backend: run via fastapi dev
    • Frontend: run independently
    • Tauri dev flow may require extra setup or is unstable
    • Known Windows-specific caveats (logging, server startup)
  3. Troubleshooting section

    • Backend starts but UI hangs
    • Server ports (8000 / 8001)
    • Firewall/network permissions
    • When to prefer EXE over dev mode

Benefit

  • Reduces onboarding friction
  • Prevents duplicate issues
  • Helps contributors understand the intended workflow
  • Clarifies Windows support expectations

If this sounds reasonable, I’m happy to open a docs PR.

Record

  • I agree to follow this project's Code of Conduct
  • I want to work on this issue

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions