Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
115 lines (87 loc) · 3.71 KB

CONTRIBUTING.md

File metadata and controls

115 lines (87 loc) · 3.71 KB

Contributing to AppSecOne

Thank you for your interest in contributing to AppSecOne! This guide will help you get started.

Development Setup

Prerequisites

  • Python 3.12 or higher
  • Git

Installation

git clone https://github.com/polprog-tech/AppSecOne.git
cd AppSecOne
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e ".[dev]"

Running the development server

appsecone serve --config appsecone.json --port 8080 --verbose

Running tests

# Full suite (464 tests)
python3 -m pytest tests/ -q

# With coverage
python3 -m pytest --cov=appsecone --cov-report=term-missing

Linting & Formatting

# Check
python3 -m ruff check src/ tests/

# Auto-fix
python3 -m ruff check --fix src/ tests/

# Format
python3 -m ruff format src/ tests/

Project Structure

src/appsecone/
├── domain/          # Pure domain models and enums (zero I/O)
├── config/          # Configuration loading and validation
├── fortify/         # Fortify SSC integration client
│   ├── client/      # HTTP client, auth, endpoints
│   └── mappers/     # DTO → domain model mapping
├── persistence/     # Database layer (SQLite)
├── application/     # Sync and query services (async)
├── analysis/        # Trend analytics & historical snapshots
├── presentation/    # Jinja2 renderer, view models, templates
│   └── templates/   # HTML templates with design system
├── web/             # FastAPI server, middleware, routes
├── cli/             # Typer CLI commands
├── i18n/            # Internationalization catalogs (EN, PL)
│   └── locales/     # JSON translation files
└── shared/          # Logging, networking, type aliases

Code Style

  • Python 3.12+ features encouraged (StrEnum, type unions, f-strings)
  • Ruff for linting and formatting (config in pyproject.toml)
  • Frozen dataclasses for domain models — immutability by default
  • Type hints everywhere — no untyped public APIs
  • Async for all I/O operations (database, network, file system)
  • CSS custom properties for all design tokens — no hardcoded colors or spacing in templates
  • No inline styles — all visual styling via CSS classes
  • CSP-safe JavaScript — all scripts use nonce attributes, no inline event handlers

Making Changes

  1. Create a feature branch: git checkout -b feature/your-feature
  2. Make your changes
  3. Run tests: python3 -m pytest tests/ -q
  4. Run linter: python3 -m ruff check src/ tests/
  5. Verify no regressions in UX/UI: python3 -m pytest tests/unit/presentation/ -q
  6. Commit with a descriptive message
  7. Open a pull request

Architecture Principles

  • Domain layer has zero I/O — pure functions and frozen dataclasses only
  • Application layer is async — all database and network calls are awaited
  • Presentation layer builds view models — no business logic in templates
  • Web layer is thin — routes delegate to services, never contain business logic
  • Config-driven policy — release readiness rules live in JSON, not code
  • Security by default — CSP headers, CSRF protection, rate limiting, API key auth

Internationalization

AppSecOne supports multiple languages. Translation catalogs live in src/appsecone/i18n/locales/.

  • Use t('key.name') in Jinja2 templates
  • Use t('key', count=N) for pluralization (keys: .one, .other, .few for Polish)
  • Always add keys to both en.json and pl.json

Reporting Issues

  • Use GitHub Issues for bug reports and feature requests
  • Include reproduction steps for bugs
  • Include expected vs actual behavior
  • For UI issues, include the browser, theme, and language used