Skip to content

windows_contributor_guide.md

Latest commit

 

History

History
455 lines (298 loc) · 6.92 KB

windows_contributor_guide.md

File metadata and controls

455 lines (298 loc) · 6.92 KB

Windows Contributor Development Guide

Overview

This guide helps Windows contributors set up SecuScan locally using PowerShell and common Windows development tools.

Prerequisites

Install the following before starting:

  • Python 3.11+
  • Node.js 20+
  • npm 10+
  • Git
  • Docker Desktop (optional)

Verify installations:

python --version
node -v
npm -v
git --version

WSL Guidance

Windows contributors can use PowerShell, Windows Terminal, or Git Bash for most contribution workflows. Windows Subsystem for Linux (WSL) is not required for general development.

WSL Is Optional

WSL is optional for:

  • Documentation updates
  • Frontend development
  • Backend development using the Windows Python installation
  • Running Git commands
  • Opening pull requests

WSL Is Recommended

WSL may provide a smoother experience when:

  • Running Linux-focused shell workflows
  • Using Bash scripts extensively
  • Working with Docker Desktop and WSL2 integration
  • Reproducing issues that occur only in Linux environments

WSL Is Out Of Scope

This guide focuses on native Windows development tools. WSL-specific setup, Linux package management, and Linux distribution configuration are not covered here.

Clone the Repository

git clone https://github.com/utksh1/SecuScan.git
cd SecuScan

If you are contributing from a fork, add the main repository as upstream so you can rebase on the latest main before opening a pull request:

git remote add upstream https://github.com/utksh1/SecuScan.git
git fetch upstream

Backend Setup

Create Virtual Environment

python -m venv venv

Activate Virtual Environment

PowerShell

.\venv\Scripts\Activate.ps1

Git Bash

source venv/Scripts/activate

Install Backend Dependencies

pip install -r backend/requirements.txt
pip install -r backend/requirements-dev.txt

Run Backend

python -m uvicorn backend.secuscan.main:app --reload --host 127.0.0.1 --port 8000

Backend should now run at:

http://127.0.0.1:8000

Swagger documentation:

http://127.0.0.1:8000/docs

If you prefer the repository helper scripts, run them from Git Bash instead of PowerShell because they are shell scripts:

./setup.sh
./start.sh

Frontend Setup

Move into the frontend directory:

cd frontend

Install dependencies:

npm install

Run the frontend:

npm run dev -- --host 127.0.0.1 --port 5173

Frontend should now run at:

http://127.0.0.1:5173

Backend Test Workflow

Use the repository test script to create the isolated venv_tests environment and install test dependencies:

./testing/test_python.sh

After the first run, you can execute a single backend test file directly.

PowerShell

.\venv_tests\Scripts\Activate.ps1
python -m pytest testing/backend/test_task_pagination.py -v
deactivate

Git Bash

source venv_tests/Scripts/activate
python -m pytest testing/backend/test_task_pagination.py -v
deactivate

Docker Setup (Optional)

Install Docker Desktop for Windows:

https://www.docker.com/products/docker-desktop/

During installation:

  • Enable WSL2 integration if prompted
  • Restart your system after installation

Verify Docker installation:

docker --version
docker compose version

Run the project stack:

docker compose up --build

If docker compose fails even though Docker Desktop is installed, open Docker Desktop first and wait until the engine reports it is running.

Common Windows Troubleshooting

PowerShell Execution Policy Error

If virtual environment activation fails with:

running scripts is disabled on this system

Run:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then retry activation.

Python PATH Issues

If python is not recognized:

  • Reinstall Python
  • Ensure "Add Python to PATH" is checked during installation

Verify again:

python --version

Node.js / npm Issues

Verify versions:

node -v
npm -v

If commands fail:

  • Reinstall Node.js
  • Restart the terminal

npm Dependency Installation Issues

Clear npm cache:

npm cache clean --force

Reinstall dependencies:

npm install

If Vite still fails to start after dependency updates, remove the existing install and reinstall from scratch:

Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm install

Git Bash vs PowerShell Command Mismatch

Use Git Bash for commands that rely on Unix shell syntax:

source venv/Scripts/activate
./testing/test_python.sh

Use PowerShell for Windows-native commands:

.\venv\Scripts\Activate.ps1

Port Already In Use

If the backend or frontend fails to start because the port is already in use, find the conflicting process and stop it.

Check which process is using the port:

netstat -ano | findstr :8000
netstat -ano | findstr :5173

Stop the process by PID:

taskkill /PID <PID> /F

Git Workflow Basics

Create a New Branch

git checkout -b feature/my-feature-name

Check Repository Status

git status

Stage Files

git add .

Commit Changes

git commit -m "docs: update Windows contributor guide"

Push Changes

git push origin feature/my-feature-name

Git Rebase Conflict Basics

Update your branch with the latest upstream changes:

git pull --rebase upstream main

If upstream does not exist yet, confirm your remotes first:

git remote -v

If conflicts appear:

  1. Open conflicted files
  2. Resolve conflicts manually
  3. Stage resolved files:
git add .
  1. Continue rebase:
git rebase --continue

Abort rebase if necessary:

git rebase --abort

Recommended Development Tools

Recommended Terminals

  • PowerShell
  • Windows Terminal

Optional:

  • Git Bash

Recommended VS Code Extensions

  • Python
  • Pylance
  • ESLint
  • Prettier
  • Docker
  • GitLens

Additional Resources

Final Notes

Before opening a pull request:

  • Ensure backend starts successfully
  • Ensure frontend starts successfully
  • Run tests if applicable
  • Verify formatting and lint checks pass
  • Keep pull requests focused and well-scoped

This guide is intended to help Windows contributors onboard faster and reduce common local setup issues.