Contributing to Ginx

Thank you for your interest in contributing to Ginx! We welcome all types of contributions - from bug reports and feature requests to code improvements and documentation updates.

🐛 Report Bugs

Found a bug? Help us fix it by providing clear details about the issue.

💡 Suggest Features

Have ideas for new functionality? We'd love to hear about features that would make Ginx more useful.

🔧 Submit Code

Fix bugs, implement features, or improve performance with code contributions.

🔌 Create Plugins

Extend Ginx functionality by building plugins for specific workflows or tools.

Development Setup

Prerequisites

• Python 3.7+ - Ginx supports modern Python versions

• Git - For version control

• Virtual environment - Recommended for isolated development

Quick Development Setup

# 1. Fork and clone the repository
git clone https://github.com/erickweyunga/ginx.git
cd ginx

# 2. Create development environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# 3. Install Ginx in development mode
pip install -e .

# 4. Install development dependencies
pip install -r requirements-dev.txt

# 5. Verify setup works
ginx version
ginx list

Using Ginx to Develop Ginx

The Ginx project uses Ginx for its own development! After setup, you can use:

ginx install                # Install ginx for development
ginx format                 # Format code with Black and isort  
ginx lint                   # Run flake8 linter
ginx typecheck              # Run MyPy type checking
ginx build                  # Build distributions
ginx clean                  # Clean build artifacts

See ginx.yaml in the project root for all available development scripts.

Code Standards

We use automated tools to maintain code quality. Run these before submitting:

Code Formatting

ginx format                 # Auto-format with Black and isort

Code Linting

ginx lint                   # Check style with flake8

Type Checking

ginx typecheck              # Verify types with MyPy

---

Submitting Issues

Bug Reports

When reporting bugs, include:

**Bug Description**
Clear description of what went wrong

**Steps to Reproduce**
1. Run `ginx command`
2. See error

**Expected Behavior**
What should have happened

**Environment**
- Ginx version: `ginx version`
- Python version: `python --version`
- OS: Linux/Mac/Windows
- Virtual environment: Yes/No

**Configuration**
```yaml
# Include relevant ginx.yaml sections
scripts:
  failing-script:
    command: "..."

Error Output

Full error message and traceback

Feature Requests

When suggesting features, include:

**Feature Description**
Clear description of the proposed feature

**Use Case**
Why would this be useful? What problem does it solve?

**Proposed Implementation**  
How might this work? (commands, configuration, etc.)

**Examples**
```bash
# How would users interact with this feature?
ginx new-command --option

Pull Request Process

Before Submitting

1. Create an issue first for major changes to discuss the approach

2. Fork the repository and create a feature branch

3. Write tests for new functionality

4. Update documentation if needed

5. Run the full test suite and ensure everything passes

Submitting Your PR

# 1. Create feature branch
git checkout -b feature/your-feature-name

# 2. Make your changes
# ... edit code ...

# 3. Test your changes  
ginx format && ginx lint && ginx typecheck && ginx test

# 4. Commit with descriptive message
git add .
git commit -m "feat: add new feature description"

# 5. Push and create PR
git push origin feature/your-feature-name

PR Requirements

• Tests pass - ginx test must succeed

• Code formatted - ginx format applied

• Linting clean - ginx lint passes

• Type checking - ginx typecheck passes

• Documentation updated - If adding features or changing behavior

• Descriptive commit messages - Use conventional commit format

Commit Message Format

Use conventional commits for clear history:

feat: add new feature
fix: resolve bug with script execution
docs: update configuration guide
test: add tests for loader validation
refactor: simplify command registration