Skip to main content
Horse is an open-source project that thrives on community contributions. Whether you’re reporting bugs, suggesting features, improving documentation, or submitting code, your contributions are valuable and appreciated.

Ways to Contribute

Report Bugs

Help identify and fix issues in Horse

Request Features

Suggest new features and improvements

Submit Code

Contribute bug fixes and new features

Improve Documentation

Help make Horse easier to learn and use

Getting Started

Fork and Clone

Start by forking the Horse repository to your GitHub account:
1

Fork the repository

Visit github.com/HashLoad/horse and click the “Fork” button.
2

Clone your fork

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

Add upstream remote

git remote add upstream https://github.com/HashLoad/horse.git
4

Create a branch

git checkout -b feature/my-new-feature

Development Environment

Horse can be developed using either Delphi or Lazarus:
Requirements:
  • Delphi XE7 or later
  • Boss package manager (recommended)
Setup:
# Install dependencies with Boss
boss install
Open Horse.dproj in Delphi IDE and build the project.

Reporting Issues

Good bug reports help maintainers understand and fix issues quickly.

Before Creating an Issue

Check if someone has already reported the same issue:
  1. Visit Horse Issues
  2. Search for keywords related to your problem
  3. Check both open and closed issues
Make sure it’s actually a bug:
  • Try with the latest version of Horse
  • Test with a minimal example
  • Check if it works in a fresh project
  • Review the documentation to ensure you’re using it correctly
Collect relevant details:
  • Horse version
  • Delphi/Lazarus version
  • Operating system
  • Steps to reproduce
  • Expected vs actual behavior

Creating a Bug Report

Create New Issue

Open a new issue on GitHub
Include in your report:
## Description
A clear description of the bug.

## Environment
- Horse Version: 3.0.0
- Delphi Version: 11.3 Alexandria
- OS: Windows 11
- Compilation Directive: HORSE_VCL

## Steps to Reproduce
1. Create a new console application
2. Add the following code...
3. Run the application
4. Send a GET request to /endpoint

## Expected Behavior
The server should return a 200 OK response.

## Actual Behavior
The server returns a 500 Internal Server Error.

## Code Sample
```delphi
uses Horse;

begin
  THorse.Get('/endpoint',
    procedure(Req: THorseRequest; Res: THorseResponse)
    begin
      // Bug occurs here
      Res.Send('test');
    end);
  
  THorse.Listen(9000);
end.

Additional Context

Error message or stack trace if available.

<Note>
The more details you provide, the easier it is to diagnose and fix the issue.
</Note>

## Suggesting Features

Feature requests help shape the future of Horse.

### Creating a Feature Request

<Steps>
  <Step title="Check existing requests">
    Search [issues](https://github.com/HashLoad/horse/issues) to see if someone already suggested it.
  </Step>
  
  <Step title="Describe the use case">
    Explain what problem your feature would solve and why it's valuable.
  </Step>
  
  <Step title="Propose a solution">
    Suggest how the feature might work, including API design if applicable.
  </Step>
  
  <Step title="Consider alternatives">
    Mention other ways the problem could be solved or workarounds you've tried.
  </Step>
</Steps>

**Feature request template:**

```markdown
## Feature Request

### Problem Statement
As a Horse developer, I often need to [describe problem]...

### Proposed Solution
Add a new method/middleware that allows [describe solution].

### Example Usage
    THorse.Use(NewFeature(options));

### Alternatives Considered
- Workaround A: [description and limitations]
- Workaround B: [description and limitations]

### Benefits
- Simplifies common use case
- Improves developer experience
- Aligns with Express.js patterns

Contributing Code

Coding Standards

Follow these conventions to maintain code consistency:
Naming Conventions:
// Classes: TPascalCase
type
  THorseRequest = class
  end;

// Methods: PascalCase
procedure ProcessRequest;

// Variables: PascalCase or camelCase for local vars
var
  RequestData: string;
  localVar: Integer;

// Constants: Pascal_Snake_Case or PascalCase
const
  DEFAULT_PORT = 9000;
Indentation:
  • Use 2 spaces for indentation
  • No tabs
Line Length:
  • Keep lines under 120 characters when practical

Testing

Test your changes before submitting:
1

Unit tests

Run existing tests to ensure nothing breaks:
# Run test suite
dcc32 Tests.dpr
./Tests.exe
2

Add new tests

Include tests for new functionality:
procedure TestNewFeature;
begin
  // Arrange
  var Request := CreateMockRequest;
  
  // Act
  var Result := MyNewFunction(Request);
  
  // Assert
  Assert.AreEqual('expected', Result);
end;
3

Manual testing

Test your changes in a real application with different scenarios.
4

Cross-platform testing

If possible, test on both Windows and Linux, and with both Delphi and Lazarus.
Horse aims for high test coverage. Current coverage:
  • Console: 45%
  • VCL: 43%
Help improve these numbers!

Submitting a Pull Request

1

Commit your changes

Write clear, descriptive commit messages:
git add .
git commit -m "Add support for custom error handlers

- Implement OnError callback in THorse
- Add example in samples/console
- Update documentation"
2

Push to your fork

git push origin feature/my-new-feature
3

Create pull request

  1. Go to your fork on GitHub
  2. Click “Pull Request”
  3. Select your branch
  4. Fill out the PR template
4

Respond to feedback

Maintainers may request changes. Address feedback promptly and professionally.
Pull Request Template:
## Description
Brief description of what this PR does.

## Related Issue
Closes #123

## Changes Made
- Added X feature
- Fixed Y bug
- Updated Z documentation

## Testing
- [ ] Unit tests pass
- [ ] Manual testing completed
- [ ] Tested on Delphi
- [ ] Tested on Lazarus
- [ ] Documentation updated

## Breaking Changes
None / [describe any breaking changes]

## Screenshots
[if applicable]

Pull Request Guidelines

  • One feature or fix per PR
  • Avoid mixing unrelated changes
  • Split large changes into multiple PRs if needed
  • Add XML doc comments for public APIs
  • Update README if behavior changes
  • Include code examples for new features
  • Avoid breaking existing APIs unless absolutely necessary
  • If breaking changes are needed, document them clearly
  • Consider deprecation warnings before removal
Use clear commit message prefixes:
  • feat: for new features
  • fix: for bug fixes
  • docs: for documentation
  • refactor: for code restructuring
  • test: for test additions/changes
  • chore: for maintenance tasks

Creating Middlewares

Extend Horse functionality by creating middlewares:

Middleware Structure

unit Horse.MyMiddleware;

interface

uses
  Horse;

function MyMiddleware: THorseCallback; overload;
function MyMiddleware(const AOptions: string): THorseCallback; overload;

implementation

function MyMiddleware: THorseCallback;
begin
  Result := MyMiddleware('default');
end;

function MyMiddleware(const AOptions: string): THorseCallback;
begin
  Result :=
    procedure(Req: THorseRequest; Res: THorseResponse; Next: TProc)
    begin
      // Pre-processing
      try
        // Your middleware logic here
        
        // Call next middleware in chain
        Next;
        
        // Post-processing (optional)
      except
        on E: Exception do
        begin
          Res.Status(500).Send('Middleware error: ' + E.Message);
        end;
      end;
    end;
end;

end.

Publishing Your Middleware

1

Create repository

Host your middleware on GitHub with:
  • Clear README with installation and usage
  • License file (MIT recommended)
  • Sample application
  • Boss configuration if applicable
2

Add to community list

Submit a PR to add your middleware to the Horse README.
3

Announce it

Share your middleware in the Telegram channel.

Community Guidelines

Code of Conduct

Be respectful and professional:
  • Be welcoming and inclusive
  • Respect differing viewpoints
  • Accept constructive criticism gracefully
  • Focus on what’s best for the community
  • Show empathy towards other members

Getting Help

Telegram Community

Ask questions and get help from other developers

GitHub Discussions

Start discussions about features and ideas

Staying Updated

1

Watch the repository

Click “Watch” on GitHub to get notified of updates.
2

Join Telegram

Connect with the community on Telegram.
3

Follow releases

Subscribe to release notifications to stay current with new versions.

License

Horse is licensed under the MIT License. By contributing, you agree that your contributions will be licensed under the same terms. MIT License Summary:
  • Commercial use allowed
  • Modification allowed
  • Distribution allowed
  • Private use allowed
  • No warranty provided

View Full License

Read the complete MIT License text

Recognition

Contributors are recognized in several ways:
  • Listed in the GitHub contributors graph
  • Mentioned in release notes for significant contributions
  • Community acknowledgment on Telegram
  • Profile linked in the README (for major contributors)

View Contributors

See all Horse contributors

Next Steps

Explore Examples

Learn from real-world Horse applications

Browse Ecosystem

Discover middlewares and tools
Thank you for contributing to Horse! Every contribution, no matter how small, helps make Horse better for everyone.

Build docs developers (and LLMs) love