Contribution Guide

This guide covers the end-to-end process for contributing to OSTwin, from local setup through pull request approval.

Prerequisites

Fork and clone the repository

git clone https://github.com/YOUR-USERNAME/os-twin.git
cd os-twin

Run the install script
Terminal window
```
.agents/install.sh
```
This creates the directory structure, installs Python dependencies, and validates prerequisites.
Install dashboard dependencies
- Frontend
- Backend
Terminal window
cd dashboard/fe pnpm install
Terminal window
cd dashboard pip install -r requirements.txt
Verify the installation
Terminal window
```
.agents/health.sh
```

Run the test suite to confirm everything works

pwsh -Command "Invoke-Pester .agents/tests/ -Output Detailed"

pytest .agents/tests/ -v

cd cypress
npx cypress run

Always branch from develop:

git checkout develop
git pull origin develop
git checkout -b feat/my-feature

Run all tests before pushing

pwsh -Command "Invoke-Pester .agents/tests/ -Output Detailed"
pytest .agents/tests/ -v

pytest .agents/tests/ -x --tb=short

Push and open a pull request against develop
Terminal window
```
git push origin feat/my-feature
```
Fill in the PR template — include a summary, test evidence, and link to any related issues
Address review feedback — maintainers will review within 48 hours

PowerShell tests use Pester 5+. Tests live alongside source files or in .agents/tests/:

pwsh -Command "Invoke-Pester .agents/tests/ -Output Detailed"

Naming convention: *.Tests.ps1

Python tests use pytest. Tests live in .agents/tests/ and dashboard/tests/:

pytest .agents/tests/ -v --cov=.agents
pytest dashboard/tests/ -v

Naming convention: test_*.py

E2E tests for the dashboard use Cypress:

cd cypress
npx cypress run
npx cypress open  # interactive mode

Tests live in cypress/e2e/.

Documentation uses Astro Starlight. To preview locally:

cd docs
pnpm install
pnpm dev

Write documentation in .md for reference pages and .mdx for interactive pages.