spec-kemal/CONTRIBUTING.md

Contributing to spec-kemal

First off, thank you for considering contributing to spec-kemal! It's people like you that make spec-kemal such a great tool.

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• Making Changes
• Testing
• Submitting Changes
• Style Guidelines
• Reporting Bugs
• Suggesting Features

Code of Conduct

This project and everyone participating in it is governed by our commitment to providing a welcoming and inclusive environment. Please be respectful and constructive in all interactions.

Getting Started

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

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

3. Add the upstream remote:

   git remote add upstream https://github.com/kemalcr/spec-kemal.git
   

Development Setup

Prerequisites

• Crystal (1.10 or later recommended)
• Git

Installing Dependencies

shards install

Running Tests

crystal spec

Or with verbose output:

crystal spec --verbose

Making Changes

1. Create a feature branch from master:

   git checkout -b my-feature-branch
   

2. Make your changes with clear, descriptive commits

3. Write or update tests for your changes

4. Ensure all tests pass:

   crystal spec
   

5. Format your code:

   crystal tool format
   

6. Check for issues (optional but recommended):

   # If you have ameba installed
   ameba
   

Testing

Running the Test Suite

# Run all tests
crystal spec

# Run specific test file
crystal spec spec/spec-kemal_spec.cr

# Run with random order
crystal spec --order=random

Writing Tests

• Place tests in the spec/ directory
• Name test files with _spec.cr suffix
• Use descriptive test names that explain what is being tested

Example:

describe "HTTP Methods" do
  describe "#get" do
    it "sends a GET request to the specified path" do
      get "/" do
        "Hello"
      end

      get "/"
      response.body.should eq "Hello"
    end

    it "includes custom headers in the request" do
      # test implementation
    end
  end
end

Submitting Changes

1. Push your branch to your fork:

   git push origin my-feature-branch
   

2. Create a Pull Request from your branch to kemalcr/spec-kemal:master

3. Fill out the PR template with:

   • A clear description of the changes
   • Any related issues (use "Fixes #123" to auto-close)
   • Screenshots if applicable (for documentation changes)

4. Wait for review - maintainers will review your PR and may request changes

PR Guidelines

• Keep PRs focused on a single feature or fix
• Include tests for new functionality
• Update documentation if needed
• Ensure CI passes before requesting review

Style Guidelines

Code Style

• Follow Crystal's standard formatting (use crystal tool format)
• Use meaningful variable and method names
• Keep methods small and focused
• Add documentation comments for public methods

Documentation Style

# Brief description of what the method does.
#
# More detailed explanation if needed, including any
# important notes or caveats.
#
# ## Parameters
#
# - `param1` : Description of param1
# - `param2` : Description of param2
#
# ## Example
#
# ```crystal
# result = my_method("value")
# result.should eq expected
# ```
#
# Returns description of return value.
def my_method(param1 : String, param2 : Int32? = nil) : ReturnType
  # implementation
end

Commit Messages

• Use present tense ("Add feature" not "Added feature")
• Use imperative mood ("Move cursor to..." not "Moves cursor to...")
• Keep the first line under 72 characters
• Reference issues when relevant

Good examples:

Add support for custom request timeout

Fix session cookie not being set correctly

Update README with session testing examples

Fixes #42

Reporting Bugs

Before Submitting

1. Search existing issues to avoid duplicates
2. Try the latest version to see if the bug has been fixed
3. Gather information about your environment

Bug Report Template

## Description
A clear description of the bug.

## Steps to Reproduce
1. Step one
2. Step two
3. ...

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Environment
- Crystal version: [e.g., 1.10.0]
- Kemal version: [e.g., 1.1.0]
- spec-kemal version: [e.g., 1.0.0]
- OS: [e.g., Ubuntu 22.04]

## Additional Context
Any other relevant information.

Suggesting Features

We welcome feature suggestions! Please:

1. Check existing issues for similar suggestions
2. Create a new issue with the "feature request" label
3. Describe the feature and its use case
4. Provide examples of how it would be used

Feature Request Template

## Feature Description
A clear description of the feature.

## Use Case
Why this feature would be useful.

## Proposed API
```crystal
# How you envision using this feature

Alternatives Considered

Other approaches you've thought about.

## Questions?

If you have questions about contributing, feel free to:

- Open an issue with the "question" label
- Reach out to maintainers

Thank you for contributing to spec-kemal! 🎉