Contributing

This project is developed as open-source software and welcomes contributions from the community. Contributions range from documentation improvements and bug fixes to architectural refinements and new functionality.

The project aims to provide a reliable, reusable on-device gateway infrastructure for sensor networks. Contributions that improve robustness, clarity, and long-term maintainability are particularly valued.

This document describes the recommended contribution process.

Human-led Contributions and AI Usage

This project welcomes contributions from human contributors only.

Automated or autonomous AI agents are not permitted to independently open issues, submit pull requests, or participate in code review or architectural discussions.

The use of AI-based tools (e.g. for drafting text, refactoring assistance, or code suggestions) is acceptable when used as a support tool by a human contributor, provided that:

  • the contributor fully understands the proposed changes,

  • the contributor takes responsibility for correctness, style, and impact,

  • all contributions are reviewed, validated, and approved by a human.

Submissions that appear to be generated or maintained primarily by autonomous agents may be closed without further review.

Contribution Workflow

To keep development transparent and manageable, most contributions follow an issue-first workflow.

In general:

  • Small documentation fixes may be submitted directly as pull requests.

  • Bug fixes, new features, and refactoring efforts should start with a GitHub issue before code is written.

Starting with an issue helps:

  • align expectations early,

  • avoid duplicated work,

  • discuss scope and design before implementation,

  • document decisions for future contributors.

Choosing the Right Issue Type

Please use the appropriate GitHub issue template when opening an issue.

Bug reports

Use the Bug Report template if you observe incorrect or unexpected behavior.

Typical examples:

  • crashes or unhandled exceptions

  • incorrect file synchronization behavior

  • OTA update failures

  • persistence or restart issues

Bug reports should include:

  • steps to reproduce the issue

  • relevant logs or error messages

  • gateway version and device environment, if available

Feature requests

Use the Feature Request template for user-facing changes or new capabilities.

Feature requests should:

  • describe the user-facing need first (user story),

  • outline a possible solution or approach (optional but helpful),

  • indicate whether you would like to implement the feature yourself.

Feature requests are evaluated based on:

  • alignment with project scope,

  • impact on long-term maintainability,

  • backward compatibility,

  • operational robustness.

Refactoring and code cleanup

Use the Refactoring / Code Cleanup template for internal improvements that do not introduce new user-facing features.

Typical refactoring proposals include:

  • simplifying complex code paths,

  • reducing duplication,

  • clarifying module responsibilities,

  • improving testability or maintainability.

Refactoring issues should clearly state:

  • motivation for the change,

  • affected components,

  • confirmation that user-facing behavior remains unchanged (or describe changes).

Development Principles

To keep the software reusable across research domains, contributions should follow these principles:

  • The gateway provides infrastructure, not application logic.

  • Sensor- or domain-specific behavior belongs in the external controller (to be implemented by the user).

  • Backward compatibility should be maintained whenever feasible.

If a proposed change significantly affects architecture, persistence, or external interfaces, please discuss it in an issue first.

Pull Requests

Once an issue has been discussed and agreed upon, you can proceed with a pull request.

Recommended steps:

  1. Fork the repository.

  2. Create a feature branch from the main branch.

  3. Implement the change with clear, focused commits.

  4. Update documentation where relevant.

  5. Open a pull request and link the related issue.

Pull requests should include:

  • a short summary of the change,

  • a reference to the related issue,

  • notes on testing or validation,

  • mention of any backward compatibility considerations.

Code Quality and Review

Contributions should aim to:

  • follow the existing code structure and style,

  • passing mypy checks,

  • avoid unnecessary dependencies,

  • keep behavior explicit and predictable.

Licensing and Acknowledgment

By contributing, you agree that your contributions will be released under the project’s open-source license.

All contributions are tracked through GitHub issues and acknowledged in the version release notes.

Getting Help

If you are unsure whether a contribution fits the project or how to proceed:

  • open an issue to discuss ideas or questions,

  • ask for guidance in a draft pull request.

Early discussion is encouraged and helps ensure contributions are effective and well-aligned.