Skip to content

Add Windows support and development guidance #931

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Ranganath-007 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add Windows support and development guidance #931

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3931471
Add Windows support and development guidance
Ranganath-007 Jan 3, 2026
7965c53
Revise CONTRIBUTING.md for clearer contribution guidelines
Ranganath-007 Jan 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
276 changes: 163 additions & 113 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,113 +1,163 @@
# 🌟 Contributing to PictoPy

Hi there! Thank you for considering contributing to **PictoPy** – we’re excited to collaborate with you. Whether you're fixing a bug, improving documentation, or suggesting a new feature — you're welcome here!

NOTE: Please do not open a PR for the issue which is not yet reviewed and labelled by the maintainer. Wait for the maintainer to give a green light.

# 🛠 Setting Up the Project

## Setup

1. Setup Using Script (Recommended only for Windows and Debian-based OS like Ubuntu): [Guide](docs/Script_Setup_Guide.md)
2. Setup Manually(Recommended for other OSes): [Guide](docs/Manual_Setup_Guide.md)

## Docs Website Setup

PictoPy documentation uses MkDocs with the Material theme and the Swagger UI plugin.

To set up and run the docs website on your local machine:

1. Ensure you have **Python 3** and **pip** installed. Navigate to the `/docs` folder.
2. Create a virtual environment:

```bash
python -m venv .docs-env
```

3. Activate the virtual environment:

```bash
# On macOS/Linux:
source .docs-env/bin/activate
# On Windows:
.docs-env\Scripts\activate
```

4. Install the required Python packages:

```bash
pip install -r requirements.txt
```

5. Start the local MkDocs server:

```bash
mkdocs serve -f ../mkdocs.yml
```

6. Open your browser and navigate to: http://127.0.0.1:8000.

7. Edit Markdown files inside the `docs/` folder. The site will automatically reload when changes are saved.

8. To build the static site for production deployment, run:

```bash
mkdocs build -f ../mkdocs.yml
```

## Testing

### Frontend

```bash
cd frontend
npm test
```

### Backend

- FastAPI
```bash
cd backend
pytest
```
- Tauri

```bash
cd frontend/src-tauri/
cargo test
```

## Building for Production

Create Signing Keys for tauri using the command:

```bash
npm run tauri signer generate
```

Set the public key in tauri.conf.json as pubkey and private key and password in Environment Variables(of your terminal) as TAURI_SIGNING_PRIVATE_KEY and TAURI_SIGNING_PRIVATE_KEY_PASSWORD

As an **example** of the private key would look like this:

```bash
TAURI_SIGNING_PRIVATE_KEY=dW50cnVzdGVkIGNvbW1lbnQ6IHJzaWduIGVuY3J5cHRlZCBzZWNyZXQga2V5ClJXUlRZMEl5NlF2SjE3cWNXOVlQQ0JBTlNITEpOUVoyQ3ZuNTdOSkwyNE1NN2RmVWQ1a0FBQkFBQUFBQUFBQUFBQUlBQUFBQU9XOGpTSFNRd0Q4SjNSbm5Oc1E0OThIUGx6SS9lWXI3ZjJxN3BESEh1QTRiQXlkR2E5aG1oK1g0Tk5kcmFzc0IvZFZScEpubnptRkxlbDlUR2R1d1Y5OGRSYUVmUGoxNTFBcHpQZ1dSS2lHWklZVHNkV1Byd1VQSnZCdTZFWlVGOUFNVENBRlgweUU9Cg==
```

```bash
TAURI_SIGNING_PRIVATE_KEY_PASSWORD=pass
```

```bash
npm run tauri build
```

## Additional Resources

- [Tauri Documentation](https://tauri.app/start/)
- [React Documentation](https://reactjs.org/docs/getting-started.html)
- [FastAPI Documentation](https://fastapi.tiangolo.com/)

## Troubleshooting

If you encounter any issues, please check the respective documentation for Tauri, React, and FastAPI. For persistent problems, feel free to open an issue in the project repository.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index XXXXXXX..YYYYYYY 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,3 +1,35 @@
-# Old CONTRIBUTING.md content removed
+# Contributing to PictoPy
+
+Thank you for your interest in contributing to PictoPy. We welcome
+contributions of all kinds, including bug fixes, documentation improvements,
+and new features.
+
+This document describes the contribution workflow, setup instructions,
+testing and build processes, and platform-specific notes.
+
+---
+
+## Setup
+
+PictoPy consists of a backend (FastAPI) and a frontend application.
+Contributors are expected to set up both components locally.
+
+### Prerequisites
+
+- Git
+- Python 3.9+
+- Node.js (LTS recommended)
+- Rust toolchain (for Tauri development)
+
+### Repository Setup
+
+1. Fork the repository and clone your fork:
+ ```bash
+ git clone https://github.com/<your-username>/PictoPy.git
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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.git

Alternatively, 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.

+ cd PictoPy
+ ```
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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.

+
+2. Create a new branch for your work:
+ ```bash
+ git checkout -b feature/my-change
+ ```
+
+3. Follow the platform-appropriate setup instructions below and in
+ `docs/setup.md`.
+
+For detailed setup options (script-based, manual, and documentation site
+setup), see `docs/setup.md`.
+
+---
+
+## Testing
+
+- Ensure backend and frontend run without errors.
+- Run test suites relevant to your changes.
+- Verify documentation renders correctly in Markdown.
+
+---
+
+## Building
+
+- Backend builds: standard FastAPI tooling.
+- Frontend/package builds: verify on your target platform.
+
+---
+
+## Troubleshooting
+
+- Verify required services are running.
+- Check logs for startup/runtime errors.
+- Ensure required ports are free.
+- See `docs/setup.md` for common pitfalls.
+
+---
+
+## 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.
Comment on lines +75 to +79
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 3, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 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"
fi

Repository: 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.md

Repository: 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 -50

Repository: 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 -20

Repository: 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 -100

Repository: 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 -100

Repository: 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:

  1. Broken Documentation References: docs/setup.md explicitly references CONTRIBUTING.md#setup, #troubleshooting, and promises "detailed instructions for Script Setup, Manual Setup, and Documentation Website Setup" — none of which exist in the current file.

  2. 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.

Copy link
Author

@Ranganath-007 Ranganath-007 Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@coderabbitai coderabbitai bot Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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!

+
+### User Workflow (Recommended)
+
+- Download latest `.exe` from releases page.
+- Launch the application.
+- On first run, grant firewall/network permissions if prompted.
+- If the app fails initially, close and reopen it.
+
+After granting permissions, the application should run normally.
+
+### Developer Workflow (Windows)
+
+Run backend manually; do not rely on Tauri auto-start:
+
+#### Backend (FastAPI)
+
+```bash
+fastapi dev
+```
+
+- FastAPI defaults to port `8000`.
+- If `8000` is in use, an alternate port (e.g., `8001`) may be configured.
+
+#### Frontend / UI
+
+- Run frontend independently.
+- Do not rely on Tauri dev to auto-start the backend.
+
+#### Tauri Dev Mode
+
+- Tauri dev may be unstable on Windows due to:
+ - Backend auto-start failures
+ - Logging recursion
+ - Server readiness race conditions
Comment on lines +111 to +113
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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 conditions

Apply 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).

+
+### Known Windows-Specific Issues
+
+- Backend auto-start via Tauri may fail
+ - Logging or server startup race conditions can occur
+ - Firewall or antivirus may block local services
+ - Port conflicts are more common
+
+### Troubleshooting (Windows)
+
+#### Backend runs but UI does not load
+
+- Confirm backend is running independently.
+- Check backend port (`8000` default; fallback `8001`).
+- Match frontend configuration to backend port.
+
+Use PowerShell to identify port conflicts:
+```powershell
+netstat -ano | findstr :8000
+```
+
+#### Diagnosing startup/logging issues
+
+- Review backend logs for errors.
+- Look for repeated startups, retries, logging recursion.
+- Run backend outside Tauri to isolate issues.
+
+#### Firewall / Antivirus interference
+
+- Allow PictoPy through Windows Defender.
+- For third-party antivirus: allow local traffic and executable.
+- Restart app after updating firewall/antivirus rules.
+
+### Windows Support Summary
+
+| Workflow | Windows Support |
+|-------------------------|---------------------|
+| Packaged `.exe` | Fully supported |
+| Backend development | Supported |
+| Frontend development | Supported |
+| Tauri dev mode | Limited / unstable |
+
+---
+
+## Additional Resources
+
+- README.md
+- docs/setup.md
+- Issue tracker
+- Pull Requests for discussion