diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 858431ef..b5f0f714 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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//PictoPy.git ++ cd PictoPy ++ ``` ++ ++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. ++ ++### 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 ++ ++### 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