---
description: >-
  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.
---

# Contributing to Ginx

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

```bash
# 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:

```bash
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

```bash
ginx format                 # Auto-format with Black and isort
```

Code Linting

```bash
ginx lint                   # Check style with flake8
```

Type Checking

```bash
ginx typecheck              # Verify types with MyPy
```

***

**Submitting Issues**

**Bug Reports**

When reporting bugs, include:

````markdown
**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:

````markdown
**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

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

* [x] **Tests pass** - `ginx test` must succeed
* [x] **Code formatted** - `ginx format` applied
* [x] **Linting clean** - `ginx lint` passes
* [x] **Type checking** - `ginx typecheck` passes
* [x] **Documentation updated** - If adding features or changing behavior
* [x] **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
```
