Skip to content

Latest commit

 

History

History
189 lines (131 loc) · 6.04 KB

developer_onboarding.md

File metadata and controls

189 lines (131 loc) · 6.04 KB

Developer Onboarding

This article is about:

  • Quick start guide for new developers joining the Hatch project
  • Essential knowledge and resources for getting productive quickly
  • Step-by-step onboarding process from setup to first contribution

Welcome to Hatch Development

This guide will help you get up to speed quickly as a new developer on the Hatch package manager project. Follow this step-by-step process to understand the system and make your first contribution.

Step 1: Understand What Hatch Is

Project Overview

Hatch is a package management system designed for MCP server packages, environments, and registry interactions.

Key Concepts

  • Environments - Isolated spaces for package installations
  • Installers - Modular components that handle different dependency types
  • Registry - Remote package discovery and retrieval system
  • Orchestrator - Coordinates multi-type dependency installation

Step 2: Set Up Your Development Environment

Prerequisites

  • Python 3.12+ installed
  • Conda or Mamba for Python environment management
  • Git for version control
  • Code editor
  • Terminal/command line access

Clone and Setup

# Clone the repository
git clone https://github.com/CrackingShells/Hatch.git
cd Hatch

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

Verify Installation

# Run basic tests to verify setup
python run_tests.py --integration

# Test CLI functionality
hatch --help

Step 3: Explore the Codebase

Start with High-Level Architecture

  1. Read System Overview - Understand the big picture
  2. Examine Component Architecture - Detailed component breakdown

Key Files to Understand

hatch/
├── cli/                            # Modular CLI package
│   ├── __main__.py                # Entry point and routing
│   ├── cli_utils.py               # Shared utilities
│   ├── cli_env.py                 # Environment handlers
│   ├── cli_package.py             # Package handlers
│   ├── cli_mcp.py                 # MCP handlers
│   └── cli_system.py              # System handlers
├── environment_manager.py          # Environment lifecycle management
├── package_loader.py              # Package loading and validation
├── registry_retriever.py          # Package downloads and caching
└── installers/                    # Installation system
    ├── dependency_installation_orchestrator.py
    ├── installer_base.py
    └── [specific installers]

Explore by Running Examples

# Create a test environment
python -m hatch env create test-env

# List environments
python -m hatch env list

# Install a package (if available)
python -m hatch install example-package

# Clean up
python -m hatch env remove test-env

Step 4: Understand the Development Workflow

Testing Strategy

Hatch uses a three-tier testing approach:

  • Development tests (dev_test_*.py) - Temporary validation during development
  • Regression tests (regression_test_*.py) - Permanent tests preventing regressions
  • Feature tests (feature_test_*.py) - Permanent tests for new features

Running Tests

# Run all tests
python run_tests.py

# Run specific test types
python run_tests.py --regression
python run_tests.py --feature

# Run tests for specific component
python run_tests.py --pattern "*environment*"

Code Quality Standards

  • Follow organization-wide Python coding standards
  • Write comprehensive docstrings
  • Implement proper error handling and logging
  • Include progress reporting for long-running operations

Step 5: Make Your First Contribution

Choose a Good First Issue

Look for issues labeled:

  • good first issue - Beginner-friendly tasks
  • documentation - Documentation improvements
  • testing - Test additions or improvements

Simple Contribution Ideas

  1. Add a test case - Find a component with incomplete test coverage
  2. Improve documentation - Add examples or clarify existing docs
  3. Fix a small bug - Look for simple bug reports
  4. Add error handling - Improve error messages or edge case handling

Follow the Contribution Process

  1. Create a branch - Use descriptive naming compatible with automated versioning (feat/, fix/, docs/)
  2. Make your changes - Follow coding standards and include tests
  3. Test thoroughly - Ensure all tests pass
  4. Submit a pull request - Follow the contribution guidelines

Step 6: Learn Advanced Topics

As You Get More Comfortable

  1. Installer Framework - Learn how to add new installers
  2. Orchestration System - Understand installation orchestration
  3. Registry Integration - Work with registry systems

Community

  • GitHub Issues - Bug reports and feature requests
  • GitHub Discussions - Questions and general discussion
  • Pull Request Reviews - Learn from code review feedback

Next Steps

After Your First Contribution

  1. Reflect on the process - What was easy? What was challenging?
  2. Identify areas of interest - Which parts of the system interest you most?
  3. Take on larger tasks - Gradually work on more complex features
  4. Help other new contributors - Share your onboarding experience

Becoming a Regular Contributor

  1. Specialize in an area - Become an expert in specific components
  2. Review others' contributions - Help with code reviews and testing
  3. Improve documentation - Keep documentation current and helpful
  4. Mentor new developers - Help onboard future contributors

Welcome to the Hatch development community! We're excited to have you contribute to making package management better for the CrackingShells ecosystem.