Contributing to hackney
View SourceThank you for your interest in contributing to hackney!
Getting Started
- Fork the repository
- Clone your fork:
git clone https://github.com/YOUR_USERNAME/hackney.git - Create a branch:
git checkout -b my-feature - Make your changes
- Run tests:
rebar3 eunit - Push and open a pull request
Pull Request Guidelines
Title Format
We use Conventional Commits for PR titles:
<type>: <description>Types:
| Type | Description |
|---|---|
feat | New feature |
fix | Bug fix |
docs | Documentation only |
refactor | Code change that neither fixes a bug nor adds a feature |
perf | Performance improvement |
test | Adding or updating tests |
chore | Maintenance tasks, dependencies |
security | Security fix |
Examples:
feat: add HTTP/3 connection poolingfix: handle timeout in async responsesdocs: update WebSocket guiderefactor: simplify connection state machineperf: reduce memory allocation in header parsingsecurity: update SSL certificate bundle
Description
Include in your PR description:
- What the change does
- Why the change is needed
- How to test it (if applicable)
Development Setup
Requirements
- Erlang/OTP 27+
- rebar3
Building
rebar3 compile
Building with QUIC support
QUIC/HTTP3 support is included automatically via the pure Erlang quic dependency - no additional build steps required.
Running Tests
# All tests
rebar3 eunit
# Specific test module
rebar3 eunit --module=hackney_conn_tests
# With verbose output
rebar3 eunit --verbose
Running Dialyzer
rebar3 dialyzer
Finding Your Way
Where Things Live maps each concept to its modules and tests. The table below tells you where to start for common changes.
| If you want to | Start in | Check with |
|---|---|---|
| Add a request option | src/hackney.erl, then src/hackney_conn.erl | hackney_integration_tests, plus the HTTP/2 and HTTP/3 tests if the option applies there |
| Change pool or checkout behaviour | src/hackney_pool.erl, src/hackney_load_regulation.erl | hackney_pool_tests and the fault and chaos suites in DEVELOPMENT.md |
| Change HTTP/2 or HTTP/3 behaviour | src/hackney_conn.erl, src/hackney_h3.erl. Check first whether the fix belongs in the h2 or quic dependency | hackney_http2_*_tests, hackney_http3_*_tests, hackney_h3_*_tests |
| Change the HTTP/1.1 parser | src/hackney_http.erl | hackney_http_tests, hackney_header_limits_tests, hackney_chunk_limit_tests |
| Add a proxy type or transport | src/hackney_http_connect.erl, src/hackney_socks5.erl, src/hackney_tcp.erl | hackney_proxy_tests, hackney_socks5_tests |
| Add a function to the public API | src/hackney.erl | A test in test/, and the matching guide in guides/ |
| Bump a dependency | rebar.config, then rebar3 upgrade --all | rebar3 eunit, rebar3 xref, rebar3 dialyzer |
Put tests in test/. Do not export functions from src/ only for tests.
Code Style
- Follow existing code conventions
- Keep functions short and focused
- Add specs for exported functions
- Update documentation for API changes
Reporting Issues
When reporting bugs, include:
- Erlang/OTP version (
erl -version) - hackney version
- Minimal reproduction case
- Expected vs actual behavior
Questions?
Open an issue or reach out to the maintainers.