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
2. Development Setup
3. Project Structure
4. Coding Standards
5. Testing
6. Pull Request Process
7. Development Workflow
8. 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:

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

3. Create a new branch for your changes:

   git checkout -b feature/your-feature-name
   

4. Install dependencies:

   go mod tidy
   

5. Run the application in development mode:

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

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:

go test ./...

Run tests with verbose output:

go test -v ./...

Run tests and show coverage:

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:

   git fetch origin
   git rebase origin/main
   

2. Push your changes to your fork:

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

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!