How to Contribute

This article is about:

  • General contribution workflow and process for the Hatch project
  • Branch naming conventions and submission requirements
  • Community standards and expectations for contributors

Overview

We welcome contributions to the Hatch project! This guide outlines the process for contributing code, documentation, and other improvements to help ensure smooth collaboration and high-quality contributions.

Before You Start

Prerequisites

  1. Understand the System - Review Architecture Documentation to understand Hatch’s design
  2. Set Up Development Environment - Follow Development Environment Setup
  3. Review Standards - Familiarize yourself with Testing Requirements and Release Policies

Planning Your Contribution

  • Check Existing Issues - Search GitHub Issues for related work
  • Discuss Major Changes - Open an issue to discuss significant changes before implementing
  • Review Implementation Guides - Check Implementation Guides for technical guidance

Contribution Workflow

1. Fork and Clone

# Fork the repository on GitHub
git fork https://github.com/CrackingShells/Hatch.git

# Clone your fork locally
git clone https://github.com/YOUR_USERNAME/Hatch.git
cd Hatch

# Add upstream remote
git remote add upstream https://github.com/CrackingShells/Hatch.git

2. Create Feature Branch

Use descriptive branch names with appropriate prefixes:

# Feature additions
git checkout -b feat/add-new-installer-type

# Bug fixes
git checkout -b fix/environment-creation-error

# Documentation updates
git checkout -b docs/update-architecture-guide

Branch Naming Conventions:

  • feat/ - New features or enhancements
  • fix/ - Bug fixes
  • docs/ - Documentation changes
  • cicd/ - CI/CD pipeline changes

3. Implement Your Changes

Code Changes

  • Follow the organization’s coding standards
  • Write clear, self-documenting code with appropriate comments
  • Include docstrings following the organization’s docstring standards
  • Implement comprehensive error handling and logging

Testing Requirements

  • Write tests for all new functionality
  • Follow the three-tier testing approach: Development, Regression, Feature
  • Ensure tests pass locally before submitting
  • Maintain or improve test coverage

Documentation Updates

  • Update relevant documentation for new features
  • Follow the organization’s documentation guidelines
  • Reference API docstrings rather than duplicating implementation details
  • Maintain clear cross-references between related topics

4. Commit Your Changes

Write clear, descriptive commit messages:

# Good commit messages
git commit -m "[Update] Add support for custom installer types"
git commit -m "[Fix] Resolve environment creation race condition"
git commit -m "[Docs - Minor] Typos in installation orchestration guide"

# Include more detail in commit body for complex changes
git commit -m "[Feat] Implement parallel dependency installation

- Add ThreadPoolExecutor for concurrent installations
- Implement dependency grouping for parallelization
- Add timeout handling for long-running installations
- Update tests to cover parallel execution scenarios"

5. Keep Your Branch Updated

# Fetch latest changes from upstream
git fetch upstream

# Rebase your branch on latest main
git rebase upstream/main

# Resolve any conflicts and continue
git rebase --continue

6. Submit Pull Request

Pull Request Guidelines

  • Clear Title - Summarize the change in the title
  • Detailed Description - Explain what changes were made and why
  • Link Related Issues - Reference any related GitHub issues
  • Testing Information - Describe how the changes were tested
  • Breaking Changes - Clearly document any breaking changes

Pull Request Template

## Description
Brief description of the changes made.

## 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

## Testing
- [ ] Tests pass locally
- [ ] New tests added for new functionality
- [ ] Manual testing performed

## Related Issues
Fixes #(issue number)

## Additional Notes
Any additional information or context about the changes.

Code Review Process

What to Expect

  • Initial Review - Maintainers will review your pull request within a few days
  • Feedback - You may receive requests for changes or improvements
  • Iteration - Work with reviewers to address feedback and refine your contribution
  • Approval - Once approved, your changes will be merged

Responding to Feedback

  • Be Responsive - Address feedback promptly and professionally
  • Ask Questions - If feedback is unclear, ask for clarification
  • Make Requested Changes - Implement suggested improvements
  • Update Tests - Ensure tests still pass after making changes

Community Standards

Communication

  • Be Respectful - Treat all community members with respect and professionalism
  • Be Constructive - Provide helpful, actionable feedback
  • Be Patient - Understand that reviews take time and maintainers are volunteers

Quality Standards

  • Follow Conventions - Adhere to established coding and documentation standards
  • Test Thoroughly - Ensure your changes work correctly and don’t break existing functionality
  • Document Changes - Provide clear documentation for new features and changes

Contribution Types

Code Contributions

  • New features and enhancements
  • Bug fixes and improvements
  • Performance optimizations
  • Refactoring and code cleanup

Documentation Contributions

  • API documentation improvements
  • Tutorial and guide updates
  • Example code and usage patterns
  • Translation and localization

Testing Contributions

  • New test cases and scenarios
  • Test infrastructure improvements
  • Performance and load testing
  • Integration test enhancements

Getting Help

Resources

Support Channels

  • GitHub Issues - For bug reports and feature requests
  • GitHub Discussions - For questions and general discussion
  • Pull Request Comments - For specific feedback on contributions

Recognition

Contributors who make significant contributions to the Hatch project will be recognized in:

  • Project documentation and release notes
  • Contributor acknowledgments
  • Community highlights and announcements

Thank you for contributing to the Hatch project! Your contributions help make package management better for the entire CrackingShells ecosystem.