GemReader/CONTRIBUTING.md

# Contributing to GemReader

Thank you for your interest in contributing to GemReader! This document provides guidelines and instructions for contributing to the project.

## Table of Contents

1. [Code of Conduct](#code-of-conduct)
2. [Development Setup](#development-setup)
3. [Project Structure](#project-structure)
4. [Coding Standards](#coding-standards)
5. [Testing](#testing)
6. [Pull Request Process](#pull-request-process)
7. [Development Workflow](#development-workflow)
8. [Reporting Issues](#reporting-issues)

## Code of Conduct

By participating in this project, you agree to abide by the following code of conduct:

- Be respectful and considerate to others
- Provide constructive feedback
- Welcome different viewpoints and experiences
- Focus on what is best for the community
- Show empathy towards other community members

## Development Setup

### Prerequisites

- Go 1.24 or higher
- Git
- A terminal that supports ANSI escape sequences

### Getting Started

1. Fork the repository on GitHub
2. Clone your fork:

   ```bash
   git clone https://github.com/YOUR-USERNAME/gemreader.git
   cd gemreader
   ```

3. Create a new branch for your changes:

   ```bash
   git checkout -b feature/your-feature-name
   ```

4. Install dependencies:

   ```bash
   go mod tidy
   ```

5. Run the application in development mode:

   ```bash
   go run cmd/gemreader/main.go sample.md
   ```

### Development Environment

For the best development experience, we recommend:

- Using a Go-aware IDE such as VS Code with Go extension, GoLand, or Vim with Go plugins
- Terminal that supports color and special characters for proper TUI rendering
- Using `go fmt` to format your code before committing

## Project Structure

```
gemreader/
├── cmd/
│   └── gemreader/
│       └── main.go                 # Application entry point
├── internal/
│   ├── config/
│   │   └── config.go              # Configuration loading
│   └── tui/
│       └── tui.go                 # Terminal user interface
├── docs/                          # Documentation files
├── config.toml                    # Default configuration
├── sample.md                      # Sample markdown file
├── go.mod                         # Go module file
├── go.sum                         # Go module checksums
├── README.md                      # Main documentation file
└── CONTRIBUTING.md                # This file
```

## Coding Standards

### Go Code Standards

- Follow the official [Go formatting conventions](https://golang.org/doc/effective_go.html)
- Use `go fmt` to format your code before committing
- Write clear, descriptive names for variables, functions, and types
- Include comments for exported functions and types
- Write idiomatic Go code following the [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments)

### Naming Conventions

- Use camelCase for variable and function names
- Use PascalCase for exported functions and types
- Use descriptive names that clearly indicate purpose
- Keep function names concise but meaningful

### Comments and Documentation

- Document exported functions and types with clear explanations
- Use complete sentences with proper capitalization and punctuation
- Include examples when helpful
- Comment complex logic to explain the "why" not just the "what"

## Testing

### Running Tests

Run all tests in the project:

```bash
go test ./...
```

Run tests with verbose output:

```bash
go test -v ./...
```

Run tests and show coverage:

```bash
go test -cover ./...
```

### Writing Tests

- Write tests for new functionality
- Ensure tests cover edge cases
- Use descriptive test names in the format `TestFunctionName_Scenario_ExpectedBehavior`
- Follow the table-driven test pattern when appropriate

### Test Structure

Tests should follow this pattern:

- Setup test data and inputs
- Execute the function under test
- Assert the results match expected outcomes
- Clean up if necessary

## Pull Request Process

### Before Submitting

1. Ensure your code follows the coding standards
2. Add tests for new functionality
3. Update documentation as needed
4. Run all tests to ensure they pass
5. Format your code with `go fmt`
6. Run linters to check for issues (e.g., `go vet ./...`)

### Creating a Pull Request

1. Ensure your branch is up to date with the main branch:

   ```bash
   git fetch origin
   git rebase origin/main
   ```

2. Push your changes to your fork:

   ```bash
   git push origin feature/your-feature-name
   ```

3. Create a pull request on GitHub
4. Fill out the pull request template (if available)
5. Provide a clear description of your changes
6. Link to any related issues

### Pull Request Review

- Allow time for others to review your code
- Be responsive to feedback and make requested changes
- Maintain a positive attitude during discussions
- Ensure all CI checks pass before merging

## Development Workflow

### New Features

1. Create an issue describing the feature (if not already created)
2. Fork and create a branch from the main branch
3. Implement the feature
4. Write tests for the new functionality
5. Update documentation as needed
6. Submit a pull request following the process above

### Bug Fixes

1. Create an issue describing the bug (if not already created)
2. Fork and create a branch from the main branch
3. Write a test that reproduces the bug
4. Implement the fix
5. Ensure the test passes
6. Submit a pull request following the process above

### Refactoring

1. Ensure all tests pass before starting
2. Make small, incremental changes
3. Run tests frequently to ensure nothing is broken
4. Submit changes as a pull request with clear description

## Reporting Issues

### Before Creating an Issue

- Check the [existing issues](https://github.com/your-repo/gemreader/issues) to avoid duplicates
- Ensure you're using the latest version of the application
- Try to reproduce the issue on different systems if possible

### Creating an Issue

When creating an issue, please include:

- Clear title and description
- Steps to reproduce the issue
- Expected behavior
- Actual behavior
- Environment information (Go version, OS, terminal)
- Any relevant screenshots or error messages

### Good Issues

- Include detailed steps to reproduce
- Provide expected vs. actual behavior
- Include environment information
- Are specific rather than broad
- Include examples when helpful

## Development Tools

### Recommended Setup

The following tools will help with development:

- **Editor**: VS Code with Go extension, GoLand, or Vim with Go plugins
- **Terminal**: A modern terminal that supports ANSI escape sequences (Windows Terminal, iTerm2, etc.)
- **Git**: Properly configured with your GitHub account

### Development Commands

Useful commands during development:

- `go run cmd/gemreader/main.go sample.md`: Run the application
- `go build -o gemreader cmd/gemreader/main.go`: Build the application
- `go build -o gemreader.exe cmd/gemreader/main.go`: Build Windows executable
- `go build -ldflags "-s -w" -o gemreader.exe cmd/gemreader/main.go`: Build optimized Windows executable
- `go test ./...`: Run all tests
- `go fmt ./...`: Format all Go files
- `go vet ./...`: Check for potential issues
- `go mod tidy`: Update dependencies

For detailed build instructions including cross-platform compilation and optimization options, see the [Building Guide](docs/building.md).

## Getting Help

If you need help with the development process:

- Open an issue with your question
- Check the documentation in the `docs/` directory
- Review existing code to see how similar features are implemented

## Recognition

All contributions are valuable to the project. Contributors will be recognized in the project documentation and release notes.

Thank you again for your interest in contributing to GemReader!