Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
110 lines (77 loc) · 2.71 KB

CONTRIBUTING.md

File metadata and controls

110 lines (77 loc) · 2.71 KB

Contributing to Sentinel

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

Prerequisites

  • Docker & Docker Compose
  • Python 3.11+
  • Git

Getting Started

1. Fork & clone

git clone https://github.com/<your-username>/Sentinel.git
cd Sentinel

2. Run the full stack with Docker

docker compose up --build

3. Run unit tests

pip install -r tests/requirements.txt
pytest

Tests run without Docker/Kafka/Spark — they are pure unit tests.

Project Structure

Directory Description
api/ FastAPI anomaly detection service
dashboard/ Streamlit visualization (4 pages)
data-generator/ Simulated & Binance market data producers
ml-python/ Isolation Forest training & evaluation
spark-java/ Spark Structured Streaming (Java/Maven)
docker/ Dockerfiles for each service
tests/ Unit tests (pytest)
docs/ Technical report & design decisions

Commit Conventions

We follow Conventional Commits:

<type>(<scope>): <short description>

Types: feat, fix, docs, style, refactor, test, chore, ci

Scopes: api, dashboard, generator, spark, ml, docker, tests, docs

Examples:

feat(api): add batch prediction endpoint
fix(dashboard): correct chart refresh interval
docs(readme): update architecture diagram
test(ml): add scaler normalization tests

Pull Request Process

  1. Create a feature branch from main:

    git checkout -b feat/my-feature

  2. Make your changes and add tests if applicable.

  3. Run the test suite:

    pytest

  4. Update CHANGELOG.md under the [Unreleased] section.

  5. Open a Pull Request against main using the PR template.

  6. Wait for CI to pass and a maintainer review.

Coding Standards

Python

  • Follow PEP 8
  • Use type hints for function signatures
  • Keep functions focused and under 50 lines when possible

Java (Spark)

  • Follow standard Java conventions
  • Use meaningful variable names

General

  • No hardcoded credentials or secrets
  • Use environment variables for configuration
  • Write descriptive commit messages

Reporting Issues

Open an issue on GitHub to report bugs or request features. Please include:

  • A clear description of the problem or suggestion
  • Steps to reproduce (for bugs)
  • Expected vs actual behavior