Skip to content

README.md

Latest commit

 

History

History
157 lines (111 loc) · 4.05 KB

README.md

File metadata and controls

157 lines (111 loc) · 4.05 KB

OSS-Dev

Open Source Contributor Operating System

Discover, understand, and contribute to open source — faster.

CI License: MIT Python 3.12+ Ruff

Quick Start

# Clone and install
git clone https://github.com/anomalyco/oss-dev.git
cd oss-dev
uv sync --dev

# Set credentials
export GITHUB_TOKEN=your_github_token
export GEMINI_API_KEY=your_gemini_api_key

# Verify
uv run oss-dev --version
uv run pytest

Vision

Open source contribution is needlessly hard. New contributors face unclear starting points, complex workflow mechanics, and overwhelming codebases. OSS-Dev is a CLI platform that:

  1. Discovers — Find projects and issues matching your skills
  2. Guides — Step-by-step mentoring through contributions
  3. Automates — Mechanical workflow (branching, commits, PRs)
  4. Analyzes — Repository intelligence for contribution readiness
  5. Connects — Community features and mentoring

Target users: First-time contributors, GSSoC/GSoC participants, students, maintainers, and developer communities.

Design principles: Contributor-first, deterministic behavior, safety gates, extensibility, professional CLI experience.

Installation

Prerequisites

  • Python 3.12+
  • Git
  • GitHub CLI (gh) — recommended for OSS features
  • Gemini API key (from Google AI Studio)

Setup

# Clone and install
git clone https://github.com/anomalyco/oss-dev.git
cd oss-dev
uv sync --dev

# Verify
uv run oss-dev --version
uv run pytest

Configuration

Set environment variables:

export GITHUB_TOKEN=your_github_token
export GEMINI_API_KEY=your_gemini_api_key

Optional project config (.oss-dev/config.toml):

[model]
name = "gemini-2.0-flash-exp"
provider = "gemini"

[oss]
enabled = true
default_base_branch = "main"

GitHub CLI Setup (Optional but Recommended)

sudo apt install gh
gh auth login

Troubleshooting

Run uv run oss-dev doctor for system diagnostics.

Commands

Global Options

Option Description
--version, -V Show version
--cwd, -C PATH Working directory
--help Show help

Command Reference

Command Description
oss-dev discover repos Find projects to contribute to
oss-dev discover issues Find issues to work on
oss-dev issues list <repo> List repository issues
oss-dev issues show <repo> <num> Show issue details
oss-dev analyze <target> Analyze a repository
oss-dev explain <path> Explain code structure
oss-dev roadmap Show contribution roadmap
oss-dev mentor <issue-url> Guided contribution workflow
oss-dev docs [query] Search documentation
oss-dev doctor Run diagnostics
oss-dev config Manage configuration

Exit Codes

Code Meaning
0 Success
1 Error
2 CLI usage error

Architecture

CLI Layer → Service Layer → Core Layer → Provider Layer
               ↓                ↓              ↓
         Intelligence      Contracts      GitHub/Git/LLM

See ARCHITECTURE.md for the complete blueprint.

Project Status

Current Version: 0.2.0 — Architecture Redesign

See ROADMAP.md for planned features and CHANGELOG.md for release history.

Contributing

We welcome contributions! See CONTRIBUTING.md to get started. Look for good first issues to find starter tasks.

Questions? Check FAQ.md or open a discussion.

License

MIT — see LICENSE