Thank you for your interest in contributing to microStore! Community contributions are greatly appreciated and help make the project better for everyone.
This document describes the expectations for issues, pull requests, and code contributions. Following these guidelines helps keep reviews focused, improves software quality, and reduces the time required to merge contributions.
Before opening an issue or submitting a pull request, please:
- Read the project documentation.
- Search existing issues and pull requests to avoid duplicates.
- Verify that the issue still exists on the latest version of the code.
- Be prepared to explain both the problem and why your proposed solution is appropriate.
A good bug report should make it easy for someone else to reproduce the problem.
Please include as much of the following information as possible:
- microStore version
- Platform and hardware
- Operating system (if applicable)
- Compiler and SDK versions (if relevant)
- Configuration used
- Steps required to reproduce the issue
- Expected behavior
- Actual behavior
- Log output
- Packet captures or traces (if applicable)
- Photographs or diagrams when hardware is involved
The easier an issue is to reproduce, the more likely it can be fixed quickly.
Feature requests should clearly describe:
- The problem being solved
- Why existing functionality is insufficient
- The proposed solution
- Possible alternatives
- Expected impact on existing users
- Any compatibility concerns
Whenever possible, describe the user problem rather than only the implementation you would like to see.
Please keep pull requests focused on a single logical change.
Good examples include:
- Fix one bug
- Add one feature
- Refactor one subsystem
- Improve one piece of documentation
Avoid combining unrelated changes such as:
- Bug fixes
- Feature additions
- Style changes
- Formatting
- Refactoring
- Documentation updates
into the same pull request.
Smaller pull requests are significantly easier to review, test, and merge.
Every pull request should begin by clearly explaining:
- What problem exists?
- Who is affected?
- How can the issue be reproduced?
- Why is the current behavior incorrect or undesirable?
Only after defining the problem should the solution be described.
Explain:
- How the change solves the problem
- Why this approach was chosen
- Any tradeoffs involved
- Any limitations
- Any compatibility implications
Reviewers should be able to understand the reasoning behind the implementation without having to infer it from the code.
Implement only the changes required to solve the stated problem.
Avoid unrelated cleanup while working on a feature or bug fix.
Large-scale refactoring should generally be submitted separately.
Contributions should:
- Be readable and maintainable.
- Follow the existing coding style.
- Avoid unnecessary complexity.
- Prefer clarity over cleverness.
- Keep functions reasonably focused.
- Avoid introducing unnecessary dependencies.
All contributions should be tested before submission.
At a minimum:
- Verify that the change solves the intended problem.
- Verify that existing functionality continues to work.
- Test edge cases where practical.
microStore supports multiple hardware platforms and environments.
If a pull request affects code shared by multiple platforms, it must be tested on every affected platform before submission.
Examples include:
- Shared protocol code
- Common libraries
- Serialization
- Packet handling
- Routing logic
- Timing
- Configuration parsing
A pull request should identify:
- Which platforms were tested
- What testing was performed
- Any platforms that were not tested and why
Contributors should not assume that successful testing on one platform guarantees correct behavior on another.
Whenever practical:
- Preserve existing APIs.
- Preserve protocol compatibility.
- Avoid breaking existing deployments.
- Clearly document any unavoidable breaking changes.
If a change affects:
- user-visible behavior,
- configuration,
- APIs,
- command-line options,
- or development workflows,
please update the relevant documentation as part of the same pull request.
Please write clear, descriptive commit messages.
Good examples:
Fix route expiration when neighbor timestamps drift
Add configurable neighbor probing interval
Prevent duplicate packet forwarding during route repair
Avoid messages such as:
fix
changes
misc
cleanup
updates
All pull requests are reviewed for:
- correctness
- maintainability
- readability
- testing
- compatibility
- project scope
Maintainers may request revisions before merging.
Submitting a pull request does not guarantee that it will be accepted.
Constructive discussion is encouraged.
Please assume good intent, remain respectful, and focus discussions on technical merits and project goals.
If you are unsure whether an idea belongs in microStore, feel free to open an issue for discussion before investing significant implementation effort.
Early discussion often saves everyone time.
Thank you for helping improve microStore!