skill-seekers-reference/CONTRIBUTING.md

Contributing to Skill Seeker

First off, thank you for considering contributing to Skill Seeker! It's people like you that make Skill Seeker such a great tool.

Table of Contents

• Branch Workflow
• Code of Conduct
• How Can I Contribute?
• Development Setup
• Pull Request Process
• Coding Standards
• Testing
• Documentation

---

Branch Workflow

⚠️ IMPORTANT: Skill Seekers uses a two-branch workflow.

Branch Structure

main (production)
  ↑
  │ (only maintainer merges)
  │
development (integration) ← default branch for PRs
  ↑
  │ (all contributor PRs go here)
  │
feature branches

Branches

• main - Production branch

  • Always stable
  • Only receives merges from development by maintainers
  • Protected: requires tests + 1 review

• development - Integration branch

  • Default branch for all PRs
  • Active development happens here
  • Protected: requires tests to pass
  • Gets merged to main by maintainers

• Feature branches - Your work

  • Created from development
  • Named descriptively (e.g., add-github-scraping)
  • Merged back to development via PR

Workflow Example

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/Skill_Seekers.git
cd Skill_Seekers

# 2. Add upstream
git remote add upstream https://github.com/yusufkaraaslan/Skill_Seekers.git

# 3. Create feature branch from development
git checkout development
git pull upstream development
git checkout -b my-feature

# 4. Make changes, commit, push
git add .
git commit -m "Add my feature"
git push origin my-feature

# 5. Create PR targeting 'development' branch

---

Related Repositories

Skill Seekers spans multiple repositories. Make sure you're contributing to the right one:

What you want to work on	Repository
Core CLI, scrapers, MCP tools, adaptors	Skill_Seekers (this repo)
Website, docs, UI/UX	skillseekersweb
Preset configs, community configs	skill-seekers-configs
GitHub Action integration	skill-seekers-action
Claude Code plugin	skill-seekers-plugin
Homebrew formula	homebrew-skill-seekers

---

Code of Conduct

This project and everyone participating in it is governed by our commitment to fostering an open and welcoming environment. Please be respectful and constructive in all interactions.

---

How Can I Contribute?

Reporting Bugs

Before creating bug reports, please check the existing issues to avoid duplicates.

When creating a bug report, include:

• Clear title and description
• Steps to reproduce the issue
• Expected behavior vs actual behavior
• Screenshots if applicable
• Environment details (OS, Python version, etc.)
• Error messages and stack traces

Example:

**Bug:** MCP tool fails when config has no categories

**Steps to Reproduce:**
1. Create config with empty categories: `"categories": {}`
2. Run `python3 cli/doc_scraper.py --config configs/test.json`
3. See error

**Expected:** Should use auto-inferred categories
**Actual:** Crashes with KeyError

**Environment:**
- OS: Ubuntu 22.04
- Python: 3.10.5
- Version: 1.0.0

Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues.

Include:

• Clear title describing the enhancement
• Detailed description of the proposed functionality
• Use cases that would benefit from this enhancement
• Examples of how it would work
• Alternatives considered

Adding New Framework Configs

We welcome new framework configurations! To add one:

1. Create a config file in configs/
2. Test it thoroughly with different page counts
3. Submit a PR with:
   • The config file
   • Brief description of the framework
   • Test results (number of pages scraped, categories found)

Example PR:

**Add Svelte Documentation Config**

Adds configuration for Svelte documentation (https://svelte.dev/docs).

- Config: `configs/svelte.json`
- Tested with max_pages: 100
- Successfully categorized: getting_started, components, api, advanced
- Total pages available: ~150

Pull Requests

We actively welcome your pull requests!

⚠️ IMPORTANT: All PRs must target the development branch, not main.

1. Fork the repo and create your branch from development
2. If you've added code, add tests
3. If you've changed APIs, update the documentation
4. Ensure the test suite passes
5. Make sure your code follows our coding standards
6. Issue that pull request to development branch!

---

Development Setup

Prerequisites

• Python 3.10 or higher (required for MCP integration)
• Git

Setup Steps

1. Fork and clone the repository

   git clone https://github.com/YOUR_USERNAME/Skill_Seekers.git
   cd Skill_Seekers
   

2. Install dependencies

   pip install requests beautifulsoup4
   pip install pytest pytest-cov
   pip install -r mcp/requirements.txt
   

3. Create a feature branch from development

   git checkout development
   git pull upstream development
   git checkout -b feature/my-awesome-feature
   

4. Make your changes

   # Edit files...
   

5. Run tests

   python -m pytest tests/ -v
   

6. Commit your changes

   git add .
   git commit -m "Add awesome feature"
   

7. Push to your fork

   git push origin feature/my-awesome-feature
   

8. Create a Pull Request

---

Pull Request Process

Before Submitting

• Tests pass locally (python -m pytest tests/ -v)
• Code follows PEP 8 style guidelines
• Documentation is updated if needed
• CHANGELOG.md is updated (if applicable)
• Commit messages are clear and descriptive

PR Template

## Description
Brief description of what this PR does.

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## How Has This Been Tested?
Describe the tests you ran to verify your changes.

## Checklist
- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

Review Process

1. A maintainer will review your PR within 3-5 business days
2. Address any feedback or requested changes
3. Once approved, a maintainer will merge your PR
4. Your contribution will be included in the next release!

---

Coding Standards

Python Style Guide

We follow PEP 8 with some modifications:

• Line length: 100 characters (not 79)
• Indentation: 4 spaces
• Quotes: Double quotes for strings
• Naming:
  • Functions/variables: snake_case
  • Classes: PascalCase
  • Constants: UPPER_SNAKE_CASE

Code Organization

# 1. Standard library imports
import os
import sys
from pathlib import Path

# 2. Third-party imports
import requests
from bs4 import BeautifulSoup

# 3. Local application imports
from cli.utils import open_folder

# 4. Constants
MAX_PAGES = 1000
DEFAULT_RATE_LIMIT = 0.5

# 5. Functions and classes
def my_function():
    """Docstring describing what this function does."""
    pass

Documentation

• All functions should have docstrings
• Use type hints where appropriate
• Add comments for complex logic

def scrape_page(url: str, selectors: dict) -> dict:
    """
    Scrape a single page and extract content.

    Args:
        url: The URL to scrape
        selectors: Dictionary of CSS selectors

    Returns:
        Dictionary containing extracted content

    Raises:
        RequestException: If page cannot be fetched
    """
    pass

Code Quality Tools

We use Ruff for linting and code formatting. Ruff is a fast Python linter that combines multiple tools (Flake8, isort, Black, etc.) into one.

Running Ruff:

# Check for linting errors
uvx ruff check src/ tests/

# Auto-fix issues
uvx ruff check --fix src/ tests/

# Format code
uvx ruff format src/ tests/

Common Ruff Rules:

• SIM102 - Simplify nested if statements (use and instead)
• SIM117 - Combine multiple with statements
• B904 - Use from e for proper exception chaining
• SIM113 - Use enumerate instead of manual counters
• B007 - Use _ for unused loop variables
• ARG002 - Remove unused function arguments

CI/CD Integration:

All pull requests automatically run:

1. ruff check - Linting validation
2. ruff format --check - Format validation
3. pytest - Test suite

Make sure all checks pass before submitting your PR:

# Run the same checks as CI
uvx ruff check src/ tests/
uvx ruff format --check src/ tests/
pytest tests/ -v

Pre-commit Setup (Optional):

You can set up pre-commit hooks to automatically run Ruff before each commit:

# Install pre-commit
pip install pre-commit

# Set up hooks (if .pre-commit-config.yaml exists)
pre-commit install

# Run manually
pre-commit run --all-files

---

Testing

Running Tests

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_mcp_server.py -v

# Run with coverage
python -m pytest tests/ --cov=cli --cov=mcp --cov-report=term

Writing Tests

• Tests go in the tests/ directory
• Test files should start with test_
• Use descriptive test names

def test_config_validation_with_missing_fields():
    """Test that config validation fails when required fields are missing."""
    config = {"name": "test"}  # Missing base_url
    result = validate_config(config)
    assert result is False

Test Coverage

• Aim for >80% code coverage
• Critical paths should have 100% coverage
• Add tests for bug fixes to prevent regressions

---

Documentation

Where to Document

• README.md - Overview, quick start, basic usage
• docs/ - Detailed guides and tutorials
• CHANGELOG.md - All notable changes
• Code comments - Complex logic and non-obvious decisions

Documentation Style

• Use clear, simple language
• Include code examples
• Add screenshots for UI-related features
• Keep it up to date with code changes

---

Project Structure

Skill_Seekers/
├── src/skill_seekers/      # Main package (src/ layout)
│   ├── cli/                # CLI commands and entry points
│   │   ├── main.py         # Unified CLI entry (COMMAND_MODULES dict)
│   │   ├── source_detector.py  # Auto-detects source type
│   │   ├── create_command.py   # Unified `create` command routing
│   │   ├── config_validator.py # VALID_SOURCE_TYPES set
│   │   ├── unified_scraper.py  # Multi-source orchestrator
│   │   ├── unified_skill_builder.py # Pairwise synthesis + generic merge
│   │   ├── doc_scraper.py      # Documentation (web)
│   │   ├── github_scraper.py   # GitHub repos
│   │   ├── pdf_scraper.py      # PDF files
│   │   ├── word_scraper.py     # Word (.docx)
│   │   ├── epub_scraper.py     # EPUB books
│   │   ├── video_scraper.py    # Video (YouTube, Vimeo, local)
│   │   ├── codebase_scraper.py # Local codebases
│   │   ├── jupyter_scraper.py  # Jupyter Notebooks
│   │   ├── html_scraper.py     # Local HTML files
│   │   ├── openapi_scraper.py  # OpenAPI/Swagger specs
│   │   ├── asciidoc_scraper.py # AsciiDoc files
│   │   ├── pptx_scraper.py     # PowerPoint files
│   │   ├── rss_scraper.py      # RSS/Atom feeds
│   │   ├── manpage_scraper.py  # Man pages
│   │   ├── confluence_scraper.py # Confluence wikis
│   │   ├── notion_scraper.py   # Notion pages
│   │   ├── chat_scraper.py     # Slack/Discord exports
│   │   ├── adaptors/          # Platform adaptors (Strategy pattern)
│   │   ├── arguments/         # CLI argument definitions (one per source)
│   │   ├── parsers/           # Subcommand parsers (one per source)
│   │   └── storage/           # Cloud storage adaptors
│   ├── mcp/                # MCP server + tools
│   └── sync/               # Sync monitoring
├── configs/                # Preset JSON scraping configs
├── docs/                   # Documentation
├── tests/                  # 115+ test files (pytest)
└── .github/               # GitHub config
    └── workflows/          # CI/CD workflows

Scraper pattern (17 source types): Each source type has cli/<type>_scraper.py (with <Type>ToSkillConverter class + main()), arguments/<type>.py, and parsers/<type>_parser.py. Register new types in: parsers/__init__.py PARSERS list, main.py COMMAND_MODULES dict, config_validator.py VALID_SOURCE_TYPES set.

UML Architecture

Full UML class diagrams are maintained in StarUML and synced from source code:

• docs/UML_ARCHITECTURE.md - Overview with embedded PNG diagrams
• docs/UML/skill_seekers.mdj - StarUML project (open with StarUML)
• docs/UML/exports/ - 14 PNG exports (package overview + 13 class diagrams)
• docs/UML/html/ - HTML API reference

Key design patterns documented in UML:

• Strategy + Factory in Adaptors (SkillAdaptor ABC + 20+ implementations)
• Strategy + Factory in Storage (BaseStorageAdaptor + S3/GCS/Azure)
• Template Method in Parsers (SubcommandParser + 28 subclasses)
• Template Method in Analysis (BasePatternDetector + 10 GoF detectors)
• Command pattern in CLI (CLIDispatcher + COMMAND_MODULES lazy dispatch)

When adding new classes or modules, please update the corresponding UML diagram to keep architecture docs in sync.

---

Release Process

Releases are managed by maintainers:

1. Update version in relevant files
2. Update CHANGELOG.md
3. Create and push version tag
4. GitHub Actions will create the release
5. Announce on relevant channels

---

Questions?

• 💬 Open a discussion
• 🐛 Report a bug
• 📧 Contact: yusufkaraaslan.yk@pm.me

---

Recognition

Contributors will be recognized in:

• README.md contributors section
• CHANGELOG.md for each release
• GitHub contributors page

Thank you for contributing to Skill Seeker! 🎉