Contributing to Eliot
View SourceThank you for considering contributing to Eliot! This document outlines the process for contributing to the project and helps to ensure your contributions can be efficiently reviewed and potentially integrated into the codebase.
Code of Conduct
This project adheres to the Contributor Covenant. By participating, you are expected to uphold this code. Please report unacceptable behavior via https://christimahu.com/contact.
How Can I Contribute?
Reporting Bugs
Bug reports are tracked as GitHub issues. When creating a bug report, please include as much detail as possible:
- Use a clear and descriptive title for the issue to identify the problem.
- Describe the exact steps to reproduce the problem in as much detail as possible.
- Provide specific examples or code snippets to demonstrate the steps.
- Describe the behavior you observed after following the steps and why you consider it a bug.
- Explain the behavior you expected to see instead and why.
- Include details about your environment (Elixir version, Erlang/OTP version, OS).
Suggesting Enhancements
Enhancement suggestions are also tracked as GitHub issues. When suggesting an enhancement:
- Use a clear and descriptive title for the issue.
- Provide a detailed description of the suggested enhancement and its expected behavior.
- Explain why this enhancement would be useful to IoT developers and the broader Elixir community.
- List similar libraries or tools where this enhancement exists, if applicable.
Code Contributions
Development Workflow
- Fork the repository on GitHub.
- Clone your fork to your local machine.
- Create a new branch from the
main
branch for your changes (git checkout -b feature/my-new-feature
). - Make your changes following the coding conventions described below.
- Write or adapt tests as necessary.
- Ensure all tests pass by running
mix test
. - Ensure code is formatted by running
mix format
. - Check code quality with
mix credo
. - Commit your changes with clear commit messages.
- Push your branch to your fork on GitHub.
- Submit a Pull Request from your branch to the project's
main
branch.
Pull Request Process
- Ensure your code follows the coding conventions.
- Update documentation as necessary.
- Add tests that verify your changes.
- Make sure all tests pass and that test coverage is maintained or improved.
- The PR should clearly describe the problem and solution.
- The PR will be reviewed by at least one maintainer.
Coding Conventions
- Code Style: The codebase follows the official Elixir Style Guide. We use Credo for static analysis to enforce these standards.
- Formatting: We use
mix format
for automated code formatting. Please run it before committing your changes. - Naming Conventions:
- Use
snake_case
for variables and function names. - Use
CamelCase
for module names.
- Use
- Comments and Documentation:
- Use ExDoc-style comments for all public modules and functions (
@moduledoc
and@doc
). - Write clear comments to explain complex or non-obvious code.
- Keep comments up-to-date with code changes.
- Use ExDoc-style comments for all public modules and functions (
- Error Handling:
- Use
{:ok, value}
and{:error, reason}
tuples for functions that can fail. - Use exceptions primarily for programmer errors (e.g., invalid arguments).
- Document expected error returns in the function's documentation.
- Use
Test Requirements
- All new code must have comprehensive tests using ExUnit.
- Pull requests must maintain or improve the current test coverage. We aim for >95% coverage.
- Tests should cover:
- Basic functionality (the "happy path").
- Edge cases (e.g., empty lists, zero values, nils).
- Error handling (invalid inputs, expected failures).
Example test structure:
defmodule Eliot.MyModuleTest do
use ExUnit.Case, async: true
describe "my_function/1" do
test "returns :ok for valid input" do
# Given: valid input
input = "valid"
# When: the function is called
result = Eliot.MyModule.my_function(input)
# Then: the result is as expected
assert {:ok, "processed"} == result
end
test "returns :error for invalid input" do
assert {:error, :invalid_input} == Eliot.MyModule.my_function(nil)
end
end
end
Development Setup
Prerequisites
- Elixir 1.14+
- Erlang/OTP 25+
Building for Development
- Clone your fork:
git clone [https://github.com/yourusername/eliot.git](https://github.com/yourusername/eliot.git) cd eliot
- Install dependencies:
mix deps.get
- Run the tests to ensure everything is working:
mix test
- To run the application in an interactive shell:
iex -S mix
Community Priorities
As a project focused on IoT data ingestion, contributions that enhance these aspects are particularly welcome:
- Reliability improvements in the
ErrorHandler
or supervision tree. - Performance enhancements for high-throughput message processing.
- Additional protocol support or improved MQTT feature handling.
- Documentation and examples that help people integrate Eliot into their systems.
- Security features that protect against common IoT vulnerabilities.
Additional Notes
Git Workflow Tips
- Keep your commits atomic and focused on a single issue.
- Write meaningful commit messages explaining the "what" and "why" of your changes.
- Rebase your branch onto the latest
main
before submitting a PR to maintain a clean history.
Questions?
If you have any questions about contributing, please open an issue and tag it with question
.
Thank you for contributing to Eliot and helping create a more robust open-source IoT ecosystem!