Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
190 lines (125 loc) · 6.46 KB

CONTRIBUTING.md

File metadata and controls

190 lines (125 loc) · 6.46 KB
Raw

Contributing to OMEGA

Thank you for your interest in contributing to OMEGA.

OMEGA — Oceanic Measurement & Environmental Geospatial Array — is an experimental open-source platform for underwater sensing, environmental data collection, logging, mapping, and geospatial visualization. The project sits at the intersection of field instrumentation, embedded systems, environmental monitoring, and data-driven research. Contributions that improve reliability, clarity, usability, and documentation are especially valuable.

Welcome

Contributions of many kinds are appreciated, including:

  • Bug reports
  • Documentation improvements
  • Code fixes and refactoring
  • Sensor integrations
  • Logging and data format improvements
  • Visualization tools
  • Mapping workflows
  • Hardware notes and deployment guidance
  • Testing and validation
  • Example datasets and sample outputs

Whether you are improving a single line of documentation or proposing a substantial new feature, thoughtful contributions are welcome.

Project Priorities

OMEGA is being developed with a strong emphasis on:

  • Reliability in real-world field use
  • Clear, readable, maintainable code
  • Modular design
  • Graceful error handling
  • Practical documentation
  • Responsible treatment of data
  • Transparent limitations and testing status

When contributing, please try to support these priorities.

Before You Contribute

Before starting work, please:

  1. Read the README.md and any relevant documentation.
  2. Check existing issues and pull requests to avoid duplication.
  3. Open an issue before beginning major changes, so the direction can be discussed first.

Small changes such as typo fixes, formatting corrections, or minor documentation improvements generally do not require a prior issue.

Reporting Bugs

High-quality bug reports are extremely helpful. When opening a bug report, please include:

  • A clear summary of the issue
  • What you expected to happen
  • What actually happened
  • Steps to reproduce the problem
  • Relevant hardware, sensors, or configuration details
  • Logs, screenshots, serial output, or error messages when available
  • Platform and toolchain information, such as board type, OS, IDE, libraries, or firmware version

The more specific the report, the easier it is to reproduce and fix the issue.

Suggesting Features

Feature suggestions are welcome, especially when they improve OMEGA’s usefulness for sensing, logging, mapping, analysis, or field deployment.

When proposing a feature, please describe:

  • The problem it solves
  • Why it would be useful
  • Any expected tradeoffs or constraints
  • A rough implementation idea, when possible

Well-scoped proposals are easier to evaluate and discuss.

Documentation Contributions

Documentation is a major part of the project. Useful contributions include:

  • Setup instructions
  • Wiring and pinout notes
  • Sensor usage guides
  • Data format explanations
  • Deployment and calibration notes
  • Troubleshooting steps
  • Example workflows
  • Clarifications for confusing or incomplete sections

Clear documentation helps make the project more usable and more durable over time.

Hardware Contributions

OMEGA includes physical hardware and field-oriented systems, so hardware-related contributions are important.

Helpful hardware contributions may include:

  • Sensor integration notes
  • Wiring diagrams
  • Enclosure recommendations
  • Waterproofing considerations
  • Power regulation improvements
  • Field deployment lessons
  • Calibration and validation methods

Please be explicit about what was tested, how it was tested, and what limitations remain.

Code Contributions

When contributing code, please aim for work that is:

  • Clear and readable
  • Modular and reasonably scoped
  • Consistent with the style of the existing codebase
  • Commented where needed for non-obvious logic
  • Defensive around failure conditions and bad inputs

OMEGA values robust behavior. Contributions should avoid brittle assumptions, silent failures, and unnecessary complexity.

Testing Expectations

Please test your changes as thoroughly as practical before opening a pull request.

Testing may include:

  • Successful compilation
  • Hardware validation
  • Serial output verification
  • Log file validation
  • Example data review
  • Basic regression testing against existing behavior

If full testing was not possible, say so clearly in the pull request. Honest notes about what was and was not tested are helpful.

Pull Request Guidelines

Before submitting a pull request, please make sure:

  1. The change has a clear and specific purpose.
  2. The pull request is focused and not trying to do too many unrelated things at once.
  3. Documentation has been updated where necessary.
  4. Testing has been performed as thoroughly as practical.
  5. Unrelated formatting or structural changes have been kept out of the same pull request.

Pull requests should include:

  • A concise summary of the change
  • Why the change was made
  • Any relevant issue references
  • Notes on testing
  • Screenshots, sample logs, or example output when useful

Smaller, focused pull requests are easier to review and merge.

Data, Logs, and Example Files

When contributing example datasets, screenshots, logs, or other sample files:

  • Do not include secrets, tokens, passwords, or private keys
  • Remove sensitive or private information
  • Clearly distinguish simulated data from real-world data
  • Document units, fields, and assumptions where possible

Good example data makes the project easier to understand and test.

Security

Please do not report security vulnerabilities through public issues.

Refer to SECURITY.md for instructions on reporting security concerns responsibly.

Conduct

Please keep discussion respectful, constructive, and focused on improving the project.

Thoughtful critique, practical collaboration, and good-faith problem-solving are encouraged. Harassment, hostility, or dismissive behavior are not acceptable.

Review and Acceptance

All contributions are reviewed on a best-effort basis.

Feedback may include requests for revision, design discussion, scope reduction, or additional testing. Not every contribution will be merged, but all thoughtful contributions are appreciated.

Licensing

By submitting code, documentation, or other materials to this project, you agree that your contributions will be made available under the MIT License.

Questions

For general questions about contributing, opening an issue is usually the best place to start so that discussion can remain visible and useful to others.

Thank you for helping improve OMEGA.