Add Windows support and development guidance #931
Conversation
Added Windows support details and troubleshooting steps for PictoPy contributors.
📝 WalkthroughWalkthroughThe CONTRIBUTING.md file was fully rewritten to replace a platform-agnostic contributor guide with a Windows-focused guide. New content adds Windows support and development workflows, known Windows-specific issues, troubleshooting, and a Windows support summary; prior generic setup, testing, and build sections were removed. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
Pre-merge checks✅ Passed checks (3 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
|
|
|
|
Added Windows support details and troubleshooting steps for PictoPy contributors. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
CONTRIBUTING.md (1)
49-66: Expand troubleshooting guidance to address known issues more comprehensively.The Known Issues list (lines 49–54) mentions logging/race conditions, firewall, and port conflicts, but the Troubleshooting section only addresses backend confirmation and firewall. Consider adding guidance for:
- How to identify and resolve port conflicts (e.g.,
netstaton Windows)- How to check logs for race conditions or server startup failures
- Specific antivirus/firewall allowlist steps if the generic "Allow through Windows Defender" is insufficient
Also, there's an inconsistent blank line at line 55 (after the known issues list).
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CONTRIBUTING.md
🔇 Additional comments (3)
CONTRIBUTING.md (3)
13-22: User Workflow section is clear and practical.The step-by-step instructions for Windows end users are straightforward, with helpful context about Firewall prompts and recovery steps. The scope is appropriately limited to packaged
.exeusage, not development.
28-47: Verify FastAPI port configuration and consider root-cause tracking for Tauri dev instability.Two concerns in the Developer Workflow section:
Port references (lines 36, 61): The guidance mentions ports
8000/8001. FastAPI's default is8000. Please confirm whether:
8001is a documented fallback when8000is occupied?- Both ports should always be checked, or is this a misconfiguration?
Tauri dev instability (lines 45-47): Documenting the workaround is helpful for contributors, but if this is a known, recurring issue ("auto startup, logging recursion, server readiness"), consider:
- Opening a tracking issue to investigate root cause
- Determining if this should be prioritized as a development experience improvement
- Clarifying whether the instability is specific to Windows or affects all platforms
68-75: Summary table provides good quick reference for Windows workflows.The table effectively summarizes support levels for each workflow. Formatting is clean and the categorization aligns with the detailed guidance above.
| +## Windows Support and Development | ||
| + | ||
| +PictoPy supports Windows primarily through the packaged `.exe` build. Local | ||
| +development on Windows is possible but differs from other platforms and has | ||
| +known limitations in the Tauri development flow. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check for related documentation and verify the scope of CONTRIBUTING.md changes
echo "=== Documentation files in the repo ==="
git ls-files | grep -iE '\.(md|txt)$' | grep -iE '(contrib|setup|readme|develop|install)' | sort
echo ""
echo "=== Full structure of docs directory if it exists ==="
git ls-files | grep '^docs/' | head -30
echo ""
echo "=== Check CONTRIBUTING.md line count and structure ==="
wc -l CONTRIBUTING.md
echo ""
echo "=== All section headers in CONTRIBUTING.md ==="
grep -n '^##' CONTRIBUTING.md
echo ""
echo "=== Check README.md for setup/contribution guidance ==="
if [ -f README.md ]; then
echo "README.md exists, checking for setup/contribution sections:"
grep -n '^##\|^#' README.md | head -20
else
echo "README.md not found"
fiRepository: AOSSIE-Org/PictoPy
Length of output: 1796
🏁 Script executed:
#!/bin/bash
# Read the full CONTRIBUTING.md to understand actual content
echo "=== Full CONTRIBUTING.md content ==="
cat -n CONTRIBUTING.mdRepository: AOSSIE-Org/PictoPy
Length of output: 2810
🏁 Script executed:
#!/bin/bash
# Check README.md for contribution guidance and documentation structure
echo "=== README.md - Want to Contribute section ==="
sed -n '/Want to Contribute/,/^#/p' README.md | head -30
echo ""
echo "=== Check if any setup guides reference CONTRIBUTING.md ==="
rg 'CONTRIBUTING|contributing' docs/ README.md -l
echo ""
echo "=== Look for git log to understand CONTRIBUTING.md changes (last few commits) ==="
git log --oneline CONTRIBUTING.md 2>/dev/null | head -10
echo ""
echo "=== Check if there's a git show for this file to see what was deleted ==="
git show HEAD:CONTRIBUTING.md 2>/dev/null | head -50Repository: AOSSIE-Org/PictoPy
Length of output: 2282
🏁 Script executed:
#!/bin/bash
# Check what docs/setup.md contains and understand documentation hierarchy
echo "=== docs/setup.md content (first 60 lines) ==="
head -60 docs/setup.md
echo ""
echo "=== Check docs/setup.md line count ==="
wc -l docs/setup.md
echo ""
echo "=== Check what docs/setup.md references about CONTRIBUTING ==="
grep -n 'CONTRIBUTING\|contributing\|contributor' docs/setup.md
echo ""
echo "=== Check the original commit to see what was in CONTRIBUTING.md before ==="
git log --all --source --remotes -S 'setup' -- CONTRIBUTING.md --oneline | head -20Repository: AOSSIE-Org/PictoPy
Length of output: 2294
🏁 Script executed:
#!/bin/bash
# Critical: Check if the referenced sections actually exist in current CONTRIBUTING.md
echo "=== Check if 'Setup' section exists in current CONTRIBUTING.md ==="
grep -n 'setup\|Setup' CONTRIBUTING.md -i
echo ""
echo "=== Check if 'Troubleshooting' section exists ==="
grep -n 'troubleshooting' CONTRIBUTING.md -i
echo ""
echo "=== Check if 'Script Setup' or 'Manual Setup' sections exist ==="
grep -n 'Script\|Manual' CONTRIBUTING.md -i
echo ""
echo "=== Get the actual git diff to see what was removed ==="
git diff HEAD~1 HEAD -- CONTRIBUTING.md | head -100Repository: AOSSIE-Org/PictoPy
Length of output: 402
🏁 Script executed:
#!/bin/bash
# Check git history to understand the state before the Windows commit
echo "=== Git log for CONTRIBUTING.md ==="
git log --oneline -- CONTRIBUTING.md | head -20
echo ""
echo "=== Show the commit before the Windows one ==="
git show b631a0ac21edfa5d0a8bdae9c7c0a3537f2368d9:CONTRIBUTING.md | head -100Repository: AOSSIE-Org/PictoPy
Length of output: 2429
CONTRIBUTING.md has been incompletely rewritten, breaking cross-platform contribution workflow and creating broken documentation links.
The previous CONTRIBUTING.md included cross-platform setup instructions, testing, and production building guidance. This has been entirely removed and replaced with Windows-only content. This creates two critical problems:
-
Broken Documentation References:
docs/setup.mdexplicitly referencesCONTRIBUTING.md#setup,#troubleshooting, and promises "detailed instructions for Script Setup, Manual Setup, and Documentation Website Setup" — none of which exist in the current file. -
Broken Contribution Entry Point: README.md directs contributors to CONTRIBUTING.md for "detailed setup instructions, coding guidelines, and the contribution process." The file now contains only Windows-specific development guidance, not contribution guidelines or setup for other platforms.
The Windows guidance itself is sound and should be included, but it should not replace platform-agnostic contribution documentation. Restore the original sections (Setup, Testing, Building, Troubleshooting, Additional Resources) alongside the new Windows content, or restructure docs/setup.md and README.md to point directly to platform-specific guides rather than CONTRIBUTING.md.
There was a problem hiding this comment.
Thank you for the detailed feedback — you’re absolutely right.
I unintentionally replaced the existing CONTRIBUTING.md content instead of
extending it, which broke cross-platform setup guidance and documentation
references.
I will restore the original sections (setup, testing, building, troubleshooting)
and include the Windows-specific guidance as an additive, platform-specific
section so existing links and contributor workflows remain intact.
There was a problem hiding this comment.
@Ranganath-007, thank you for understanding and committing to fix this! Your approach is perfect — keeping the Windows-specific guidance as an additive section while preserving the original cross-platform content will maintain the integrity of the contribution workflow and all existing documentation links.
If you need any assistance while restoring the original sections or integrating the Windows content, feel free to ask. Looking forward to the updated version! 🚀
/)/)
( •.•)
(> 🎉
If you found this review helpful, would you consider giving us a shout-out on X?
Thank you for using CodeRabbit!
Updated the CONTRIBUTING.md file to include detailed setup, testing, building, and troubleshooting instructions for contributors, with a focus on Windows support.
|
|
1 similar comment
|
|
There was a problem hiding this comment.
Actionable comments posted: 3
📜 Review details
Configuration used: defaults
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
CONTRIBUTING.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
CONTRIBUTING.md
34-34: Bare URL used
(MD034, no-bare-urls)
36-36: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
41-41: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
111-111: Unordered list indentation
Expected: 2; Actual: 3
(MD007, ul-indent)
112-112: Unordered list indentation
Expected: 2; Actual: 3
(MD007, ul-indent)
113-113: Unordered list indentation
Expected: 2; Actual: 3
(MD007, ul-indent)
118-118: Unordered list indentation
Expected: 2; Actual: 3
(MD007, ul-indent)
119-119: Unordered list indentation
Expected: 2; Actual: 3
(MD007, ul-indent)
120-120: Unordered list indentation
Expected: 2; Actual: 3
(MD007, ul-indent)
🔇 Additional comments (4)
CONTRIBUTING.md (4)
51-63: Generic Testing and Building sections appropriately restored.These sections provide high-level guidance and correctly defer to
docs/setup.mdfor detailed platform-specific instructions. This restores the cross-platform contribution workflow that was missing in the previous version.
66-71: Generic Troubleshooting section appropriately restored.This section restores platform-agnostic troubleshooting guidance and correctly references
docs/setup.mdfor detailed platform-specific issues, maintaining the documentation reference chain.
75-154: Windows Support section is comprehensive and well-structured.The Windows-specific guidance is detailed, practical, and clearly separates user workflows from developer workflows. The troubleshooting steps are actionable, and the support matrix clearly communicates compatibility expectations. This section properly augments (rather than replaces) the platform-agnostic contribution workflow, addressing the critical issue flagged in the previous review.
158-162: Cross-platform contribution workflow successfully restored.The CONTRIBUTING.md now properly restores the original platform-agnostic sections (Setup, Testing, Building, Troubleshooting) alongside the new Windows-specific guidance. This fixes the critical issue from the previous review where broken documentation links and missing cross-platform guidance would have prevented non-Windows contributors from following the workflow. The document structure clearly guides contributors to either platform-specific guidance or
docs/setup.mdfor detailed instructions.
| + | ||
| +1. Fork the repository and clone your fork: | ||
| + ```bash | ||
| + git clone https://github.com/<your-username>/PictoPy.git |
There was a problem hiding this comment.
Format bare URL as a Markdown link.
Line 34 contains a bare URL that should be wrapped in Markdown link syntax for proper rendering.
🔎 Proposed fix
- git clone https://github.com/<your-username>/PictoPy.git
+ git clone https://github.com/\<your-username\>/PictoPy.gitAlternatively, if this is intended as a code template for users to fill in, consider wrapping it in backticks or clarifying with a comment. The linter is flagging this as a bare URL.
Committable suggestion skipped: line range outside the PR's diff.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
34-34: Bare URL used
(MD034, no-bare-urls)
🤖 Prompt for AI Agents
In CONTRIBUTING.md around line 34, the line contains a bare URL "git clone
https://github.com/<your-username>/PictoPy.git"; replace it with a
Markdown-formatted link like [git clone
https://github.com/<your-username>/PictoPy.git](https://github.com/<your-username>/PictoPy.git)
or, if you intended it as a fill-in template, wrap the URL in backticks (`git
clone https://github.com/<your-username>/PictoPy.git`) or add clarifying text so
it is not treated as a bare URL by the linter.
| + ```bash | ||
| + git clone https://github.com/<your-username>/PictoPy.git | ||
| + cd PictoPy | ||
| + ``` |
There was a problem hiding this comment.
Specify language identifiers for fenced code blocks.
Code blocks on lines 36 and 41 are missing language specifiers, which improves syntax highlighting and readability.
🔎 Proposed fixes
2. Create a new branch for your work:
- ```bash
+ ```bash
git checkout -b feature/my-change
```Both code blocks should be marked as bash for proper formatting.
Also applies to: 41-41
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
36-36: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
CONTRIBUTING.md around lines 36 and 41: the fenced code blocks are missing
language identifiers; update both opening triple-backtick fences to specify
"bash" (i.e., replace ``` with ```bash for the code blocks at those lines) so
syntax highlighting and readability are improved.
| + - Backend auto-start failures | ||
| + - Logging recursion | ||
| + - Server readiness race conditions |
There was a problem hiding this comment.
Fix unordered list indentation in Windows section.
Lines 111–113 and 118–120 have incorrect indentation for nested bullet points. Markdown expects 2-space indentation for sub-bullets; these are using 3 spaces.
🔎 Proposed fixes
#### Tauri Dev Mode
-- Tauri dev may be unstable on Windows due to:
- - Backend auto-start failures
- - Logging recursion
- - Server readiness race conditions
+- Tauri dev may be unstable on Windows due to:
+ - Backend auto-start failures
+ - Logging recursion
+ - Server readiness race conditionsApply the same fix to lines 118–120 (the "Backend auto-start via Tauri may fail" bullet point).
Also applies to: 118-120
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
111-111: Unordered list indentation
Expected: 2; Actual: 3
(MD007, ul-indent)
112-112: Unordered list indentation
Expected: 2; Actual: 3
(MD007, ul-indent)
113-113: Unordered list indentation
Expected: 2; Actual: 3
(MD007, ul-indent)
🤖 Prompt for AI Agents
In CONTRIBUTING.md around lines 111-113 and 118-120 (Windows section), the
nested unordered list items use 3-space indentation for sub-bullets; change
those sub-bullets to use 2-space indentation to conform to Markdown nested-list
formatting (replace each leading 3-space indent with 2 spaces so the sub-bullets
align consistently under their parent bullet).
1 participant
Added Windows support details and troubleshooting steps for PictoPy contributors.
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.