From 40e1219586f884ff48d609c48acbef71542cb79f Mon Sep 17 00:00:00 2001 From: Omkar Mujumdar Date: Mon, 10 Nov 2025 14:03:08 +0530 Subject: [PATCH 1/9] Complete preparation of ApraUtils for public open-source release under MIT License. - Update all 48 source files with Apra Labs copyright headers - Remove auto-generated TODO comments from codebase - Add comprehensive README.md with badges and documentation - Add CONTRIBUTING.md with development guidelines - Add CODE_OF_CONDUCT.md (Contributor Covenant v2.1) - Add SECURITY.md with vulnerability reporting process - Create 5 comprehensive examples (GPIO, I2C, PWM, USB, Threading) - Add examples documentation and usage guides - Configure Doxygen for API documentation generation - Add GitHub issue templates (bug report, feature request) - Add pull request template with comprehensive checklist - Create CHANGELOG.md following Keep a Changelog format - Add GitHub Pages workflow for automated documentation - Enhance CI/CD with code coverage reporting (lcov) - Create comprehensive packaging guide (deb, rpm, Conan, vcpkg) --- .github/ISSUE_TEMPLATE/bug_report.yml | 136 + .github/ISSUE_TEMPLATE/feature_request.yml | 159 ++ .github/pull_request_template.md | 121 + .github/workflows/c-cpp.yml | 17 +- .github/workflows/documentation.yml | 50 + CHANGELOG.md | 162 ++ CODE_OF_CONDUCT.md | 132 + CONTRIBUTING.md | 453 +++ Doxyfile | 2970 ++++++++++++++++++++ PACKAGING.md | 714 +++++ README.md | 278 ++ examples/README.md | 262 ++ examples/gpio_example.cpp | 267 ++ examples/i2c_example.cpp | 272 ++ examples/pwm_example.cpp | 340 +++ examples/threading_example.cpp | 519 ++++ examples/usb_storage_example.cpp | 406 +++ includes/ApraUtils.h | 8 +- includes/constants/EventCallbacks.h | 8 +- includes/constants/I2CMessageType.h | 8 +- includes/constants/MessageType.h | 8 +- includes/constants/StorageState.h | 8 +- includes/constants/StorageType.h | 8 +- includes/constants/ThreadType.h | 8 +- includes/controllers/I2CInterface.h | 8 +- includes/models/GenericError.h | 8 +- includes/models/I2CError.h | 8 +- includes/models/I2CMessage.h | 8 +- includes/models/I2CTransactionMessage.h | 8 +- includes/models/Message.h | 8 +- includes/models/Range.h | 8 +- includes/models/StorageMinimalInfo.h | 8 +- includes/utils/FileIO.h | 8 +- includes/utils/GPIO.h | 8 +- includes/utils/I2CBus.h | 8 +- includes/utils/Macro.h | 8 +- includes/utils/Mutex.h | 8 +- includes/utils/PWM.h | 8 +- includes/utils/ProcessThread.h | 8 +- includes/utils/RealHexParser.h | 8 +- includes/utils/ScopeFunction.h | 8 +- includes/utils/ScopeLock.h | 11 + includes/utils/StorageUSB.h | 8 +- includes/utils/Utils.h | 8 +- src/constants/StorageType.cpp | 8 +- src/controllers/I2CInterface.cpp | 10 +- src/models/GenericError.cpp | 11 +- src/models/I2CError.cpp | 10 +- src/models/I2CMessage.cpp | 11 +- src/models/I2CTransactionMessage.cpp | 9 +- src/models/Message.cpp | 8 +- src/models/Range.cpp | 11 +- src/models/StorageMinimalInfo.cpp | 11 +- src/utils/FileIO.cpp | 12 +- src/utils/GPIO.cpp | 10 +- src/utils/I2CBus.cpp | 10 +- src/utils/Mutex.cpp | 8 +- src/utils/PWM.cpp | 10 +- src/utils/ProcessThread.cpp | 8 +- src/utils/RealHexParser.cpp | 10 +- src/utils/ScopeFunction.cpp | 10 +- src/utils/ScopeLock.cpp | 8 +- src/utils/StorageUSB.cpp | 10 +- src/utils/Utils.cpp | 10 +- 64 files changed, 7543 insertions(+), 129 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/documentation.yml create mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 Doxyfile create mode 100644 PACKAGING.md create mode 100644 README.md create mode 100644 examples/README.md create mode 100644 examples/gpio_example.cpp create mode 100644 examples/i2c_example.cpp create mode 100644 examples/pwm_example.cpp create mode 100644 examples/threading_example.cpp create mode 100644 examples/usb_storage_example.cpp diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..d90d5e4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,136 @@ +name: Bug Report +description: File a bug report to help us improve +title: "[Bug]: " +labels: ["bug", "triage"] +assignees: [] + +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to fill out this bug report! Please provide as much detail as possible. + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is. + placeholder: Describe the bug... + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Steps to Reproduce + description: Steps to reproduce the behavior + placeholder: | + 1. Initialize GPIO pin '...' + 2. Call method '...' + 3. See error + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What you expected to happen + placeholder: Describe what should happen... + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened + placeholder: Describe what actually happened... + validations: + required: true + + - type: input + id: version + attributes: + label: ApraUtils Version + description: What version of ApraUtils are you using? + placeholder: "e.g., 1.0.0 or commit SHA" + validations: + required: true + + - type: dropdown + id: os + attributes: + label: Operating System + description: What OS are you running? + options: + - Ubuntu 22.04 + - Ubuntu 20.04 + - Debian Bullseye + - Raspberry Pi OS + - Other Linux (specify in additional context) + validations: + required: true + + - type: input + id: compiler + attributes: + label: Compiler Version + description: Which C++ compiler and version? + placeholder: "e.g., GCC 11.2, Clang 14.0" + validations: + required: false + + - type: input + id: hardware + attributes: + label: Hardware Platform + description: What hardware are you using? + placeholder: "e.g., Raspberry Pi 4, BeagleBone Black, x86_64" + validations: + required: false + + - type: textarea + id: code + attributes: + label: Code Sample + description: Minimal code to reproduce the issue + placeholder: | + ```cpp + // Your code here + ``` + render: cpp + validations: + required: false + + - type: textarea + id: logs + attributes: + label: Error Messages / Logs + description: Any relevant error messages or logs + placeholder: Paste error output here... + render: shell + validations: + required: false + + - type: textarea + id: context + attributes: + label: Additional Context + description: Any other context about the problem + placeholder: Add any other context, screenshots, or information... + validations: + required: false + + - type: checkboxes + id: terms + attributes: + label: Checklist + description: Please confirm the following + options: + - label: I have searched existing issues to avoid duplicates + required: true + - label: I have provided all required information + required: true + - label: I am using a supported platform (Linux) + required: true diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..e6bd33f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,159 @@ +name: Feature Request +description: Suggest an idea or enhancement for ApraUtils +title: "[Feature]: " +labels: ["enhancement"] +assignees: [] + +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a new feature! Your ideas help make ApraUtils better for everyone. + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: Is your feature request related to a problem? Please describe. + placeholder: "I'm frustrated when..." + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like + placeholder: "I would like ApraUtils to..." + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Describe any alternative solutions or features you've considered + placeholder: "Alternative approaches could be..." + validations: + required: false + + - type: dropdown + id: category + attributes: + label: Feature Category + description: Which area does this feature relate to? + options: + - GPIO + - I2C + - PWM + - USB Storage + - Threading + - Error Handling + - Documentation + - Build System + - New Hardware Interface + - Other + validations: + required: true + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - Critical - Blocking my project + - High - Very important + - Medium - Would be nice to have + - Low - Minor enhancement + validations: + required: true + + - type: textarea + id: use-case + attributes: + label: Use Case + description: Describe how you would use this feature + placeholder: | + In my project, I need to... + This feature would allow me to... + validations: + required: true + + - type: textarea + id: example + attributes: + label: Example API / Usage + description: If applicable, show how you envision using this feature + placeholder: | + ```cpp + // Example usage + apra::NewFeature feature; + feature.doSomething(); + ``` + render: cpp + validations: + required: false + + - type: textarea + id: implementation + attributes: + label: Implementation Ideas + description: Do you have ideas about how this could be implemented? + placeholder: "This could be implemented by..." + validations: + required: false + + - type: dropdown + id: breaking + attributes: + label: Breaking Change + description: Would this be a breaking change to existing APIs? + options: + - "No - Backward compatible" + - "Yes - Breaking change required" + - "Not sure" + validations: + required: true + + - type: textarea + id: similar + attributes: + label: Similar Features in Other Libraries + description: Have you seen similar features in other libraries? + placeholder: "Library X has a similar feature that..." + validations: + required: false + + - type: textarea + id: context + attributes: + label: Additional Context + description: Add any other context, diagrams, or screenshots + placeholder: "Additional information..." + validations: + required: false + + - type: checkboxes + id: contribution + attributes: + label: Contribution + description: Are you willing to contribute to this feature? + options: + - label: I am willing to submit a pull request for this feature + required: false + - label: I can help with testing this feature + required: false + - label: I can help with documentation for this feature + required: false + + - type: checkboxes + id: terms + attributes: + label: Checklist + description: Please confirm the following + options: + - label: I have searched existing issues/PRs to avoid duplicates + required: true + - label: This feature aligns with the project's goals (embedded Linux utilities) + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..5743e06 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,121 @@ +# Pull Request + +## Description + + + +## Type of Change + + + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Code refactoring (no functional changes) +- [ ] Performance improvement +- [ ] Test addition/improvement +- [ ] Build/CI improvement + +## Related Issues + + + +Fixes # +Related to # + +## Changes Made + + + +- +- +- + +## Testing + +### Test Environment + +- **OS**: +- **Hardware**: +- **Compiler**: + +### Testing Performed + + + +- [ ] Unit tests (all passing) +- [ ] Integration tests +- [ ] Manual testing on hardware +- [ ] Tested on multiple platforms +- [ ] Performance testing + +### Test Results + + + +``` +Paste test output here +``` + +## Code Quality + +- [ ] Code follows the project's coding standards +- [ ] Self-review of code performed +- [ ] Comments added for complex or unclear code +- [ ] No new compiler warnings introduced +- [ ] Code is properly formatted + +## Documentation + +- [ ] Updated README.md (if user-facing changes) +- [ ] Updated API documentation / Doxygen comments +- [ ] Updated CONTRIBUTING.md (if development workflow changed) +- [ ] Added/updated examples (if new feature) +- [ ] Updated CHANGELOG.md + +## Breaking Changes + + + +### Impact + + + +### Migration Guide + + + +## Additional Notes + + + +## Checklist + +- [ ] I have read the [CONTRIBUTING.md](../CONTRIBUTING.md) guidelines +- [ ] My code follows the project's coding standards +- [ ] All existing and new tests pass +- [ ] I have added tests for my changes +- [ ] Documentation has been updated +- [ ] No sensitive information (passwords, API keys, etc.) is included +- [ ] Commit messages follow conventional commit format +- [ ] Changes are focused and atomic (one feature/fix per PR) +- [ ] I have rebased on the latest main branch +- [ ] I have resolved any merge conflicts + +## Screenshots (if applicable) + + + +## Performance Impact + + + +- [ ] No performance impact +- [ ] Performance improved +- [ ] Performance may be affected (please explain) + + diff --git a/.github/workflows/c-cpp.yml b/.github/workflows/c-cpp.yml index ba94cb6..1f54ad2 100644 --- a/.github/workflows/c-cpp.yml +++ b/.github/workflows/c-cpp.yml @@ -15,18 +15,29 @@ jobs: - name: Install dependencies run: | sudo apt-get update - sudo apt-get install -y cmake libudev-dev + sudo apt-get install -y cmake libudev-dev lcov - name: Create build directory run: mkdir -p build - name: Configure run: | cd build - cmake .. + cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS="--coverage -fprofile-arcs -ftest-coverage" -DCMAKE_C_FLAGS="--coverage -fprofile-arcs -ftest-coverage" -DCMAKE_EXE_LINKER_FLAGS="--coverage" .. - name: Build run: | cd build make - - name: Publish artifact + - name: Generate coverage report + run: | + cd build + lcov --capture --directory . --output-file coverage.info + lcov --remove coverage.info '/usr/*' '*/test/*' --output-file coverage.info + lcov --list coverage.info + - name: Upload coverage artifact + uses: actions/upload-artifact@v4 + with: + name: coverage-report + path: build/coverage.info + - name: Publish library artifact uses: actions/upload-artifact@v4 with: name: libApraUtils diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..f21d0e4 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,50 @@ +name: Documentation + +on: + push: + branches: [ "main" ] + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install Doxygen + run: | + sudo apt-get update + sudo apt-get install -y doxygen graphviz + + - name: Generate documentation + run: | + doxygen Doxyfile + + - name: Setup Pages + uses: actions/configure-pages@v4 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'docs/html' + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..efff7dc --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,162 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Planned +- Unit test coverage +- Additional hardware interface support (SPI, UART) +- Package distribution (apt, Conan, vcpkg) +- Performance benchmarking suite +- Comprehensive Doxygen documentation +- Code coverage reporting + +## [1.0.0] - Initial Open Source Release + +### Added +- **Core Hardware Interfaces** + - GPIO control with interrupt support (RISING, FALLING, BOTH edges) + - I2C asynchronous transaction management with error handling + - PWM control with nanosecond precision + - USB storage device detection and management + +- **Utilities** + - ProcessThread for multi-threaded applications with message passing + - Mutex and ScopeLock for thread synchronization + - FileIO utilities for embedded systems + - RealHexParser for numeric conversions + - Utils class with common utility functions + - ScopeFunction for function tracing + - Macro definitions for timing and utilities + +- **Data Models** + - Message and I2CMessage for inter-thread communication + - I2CTransactionMessage for complex I2C operations + - GenericError and I2CError for comprehensive error reporting + - Range for numeric range management + - StorageMinimalInfo for USB storage information + +- **Constants and Enums** + - I2CMessageType (READ, WRITE, READ_COMPARE) + - MessageType (REQUEST_ONLY, REQUEST_RESPONSE) + - ThreadType (FREERUNNING, MESSAGE_AND_FREERUNNING, ONLY_MESSAGE) + - StorageType (FAT32, NTFS, EXT4) + - StorageState (INSERTED, MOUNTED, SAFE_EJECT, UNSAFE_EJECT) + - EventCallbacks for I2C transaction callbacks + +- **Build System** + - CMake build configuration (CMakeLists.txt) + - C++14 standard support + - Static library output (libApraUtils.a) + - GitHub Actions CI/CD pipeline + +- **Documentation** + - Comprehensive README.md with badges and examples + - CONTRIBUTING.md with development guidelines + - CODE_OF_CONDUCT.md (Contributor Covenant v2.1) + - SECURITY.md with vulnerability reporting process + - MIT License + +- **Examples** + - GPIO control examples (gpio_example.cpp) + - I2C communication examples (i2c_example.cpp) + - PWM control examples (pwm_example.cpp) + - USB storage management examples (usb_storage_example.cpp) + - Multi-threading examples (threading_example.cpp) + - Examples README with usage instructions + +- **GitHub Templates** + - Bug report issue template + - Feature request issue template + - Pull request template + +- **API Documentation Setup** + - Doxygen configuration (Doxyfile) + - Source code documentation structure + +### Changed +- Updated all source file headers with Apra Labs copyright +- Standardized author attribution to "Apra Labs" +- Cleaned up auto-generated TODO comments +- Improved code organization and structure + +### Fixed +- Fixed missing platform check in I2CInterface +- Added missing header includes (cstdint, stdexcept, time.h) +- Corrected protected member access in I2CInterface +- Improved error handling in I2C bus operations + +### Platform Support +- **Operating Systems**: Linux (embedded systems focus) +- **Architectures**: ARM, x86, x86_64 +- **Tested On**: Ubuntu 22.04, Raspberry Pi OS +- **Compiler Support**: GCC 5.0+, Clang 3.8+ + +### Dependencies +- pthread (POSIX threads) +- libudev-dev (USB device enumeration) +- Linux kernel headers (I2C, GPIO, PWM interfaces) +- CMake 3.10+ + +### Breaking Changes +- None (initial release) + +### Security +- No known vulnerabilities +- Proper input validation in all public APIs +- Thread-safe operations using provided synchronization primitives + +### Performance +- Asynchronous I2C transactions for non-blocking operations +- Efficient GPIO interrupt handling +- Optimized memory usage with RAII patterns + +### Known Issues +- None currently reported + +### Contributors +- Apra Labs development team + +--- + +## Version History Format + +### [Version] - YYYY-MM-DD + +#### Added +- New features and capabilities + +#### Changed +- Changes to existing functionality + +#### Deprecated +- Soon-to-be removed features + +#### Removed +- Removed features + +#### Fixed +- Bug fixes + +#### Security +- Security fixes and improvements + +--- + +## Links + +- [Repository](https://github.com/Apra-Labs/ApraUtils) +- [Issues](https://github.com/Apra-Labs/ApraUtils/issues) +- [Pull Requests](https://github.com/Apra-Labs/ApraUtils/pulls) +- [Releases](https://github.com/Apra-Labs/ApraUtils/releases) + +--- + +**Note**: This project follows [Semantic Versioning](https://semver.org/): +- MAJOR version for incompatible API changes +- MINOR version for backwards-compatible new functionality +- PATCH version for backwards-compatible bug fixes diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..4197db8 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement at +[contact@apralabs.com](mailto:contact@apralabs.com). +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9199949 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,453 @@ +# Contributing to ApraUtils + +Thank you for considering contributing to ApraUtils! We welcome contributions from the community and are grateful for your support. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Suggesting Enhancements](#suggesting-enhancements) + - [Code Contributions](#code-contributions) +- [Development Setup](#development-setup) +- [Coding Standards](#coding-standards) +- [Commit Message Guidelines](#commit-message-guidelines) +- [Pull Request Process](#pull-request-process) +- [Testing](#testing) +- [Documentation](#documentation) + +## Code of Conduct + +This project and everyone participating in it is governed by our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers. + +## How Can I Contribute? + +### Reporting Bugs + +Before creating bug reports, please check the [existing issues](https://github.com/Apra-Labs/ApraUtils/issues) to avoid duplicates. + +When creating a bug report, please include: + +- **Clear title and description**: Describe what you expected to happen and what actually happened +- **Steps to reproduce**: Provide specific examples to reproduce the issue +- **Environment details**: + - OS version and distribution (e.g., Ubuntu 22.04, Raspbian Bullseye) + - Compiler version (e.g., GCC 11.2) + - CMake version + - Hardware platform if relevant +- **Code sample**: Minimal reproducible example if possible +- **Error messages**: Complete error output or logs +- **Screenshots**: If applicable + +**Template:** +```markdown +**Description:** +Brief description of the issue + +**Steps to Reproduce:** +1. Step 1 +2. Step 2 +3. ... + +**Expected Behavior:** +What should happen + +**Actual Behavior:** +What actually happens + +**Environment:** +- OS: Ubuntu 22.04 +- Compiler: GCC 11.2 +- CMake: 3.22.1 +- Hardware: Raspberry Pi 4 + +**Additional Context:** +Any other relevant information +``` + +### Suggesting Enhancements + +Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion: + +- **Use a clear and descriptive title** +- **Provide a detailed description** of the proposed functionality +- **Explain why this enhancement would be useful** to most ApraUtils users +- **List any similar features** in other libraries +- **Include code examples** if applicable + +### Code Contributions + +We actively welcome your pull requests! Here's how to contribute code: + +1. Fork the repository +2. Create your feature branch +3. Make your changes +4. Test your changes +5. Commit your changes +6. Push to your fork +7. Submit a pull request + +## Development Setup + +### Prerequisites + +```bash +# Ubuntu/Debian +sudo apt-get update +sudo apt-get install -y build-essential cmake git libudev-dev + +# Additional tools for development +sudo apt-get install -y clang-format clang-tidy doxygen graphviz +``` + +### Setting Up Your Development Environment + +```bash +# 1. Fork and clone the repository +git clone https://github.com/YOUR_USERNAME/ApraUtils.git +cd ApraUtils + +# 2. Add upstream remote +git remote add upstream https://github.com/Apra-Labs/ApraUtils.git + +# 3. Create a development branch +git checkout -b feature/your-feature-name + +# 4. Build the project +mkdir build && cd build +cmake .. +make + +# 5. Make your changes and test +# Edit files... +make +# Run tests... + +# 6. Commit and push +git add . +git commit -m "Add feature: description" +git push origin feature/your-feature-name +``` + +### Keeping Your Fork Updated + +```bash +git fetch upstream +git checkout main +git merge upstream/main +git push origin main +``` + +## Coding Standards + +### C++ Standards + +- **Language Standard**: C++14 +- **Compiler Compatibility**: GCC 5.0+, Clang 3.8+ +- **Platform**: Linux only + +### Code Style + +We follow a consistent coding style to maintain readability: + +#### Naming Conventions + +```cpp +// Namespaces: lowercase +namespace apra { + +// Classes: PascalCase +class ProcessThread { + +// Public member variables: m_ prefix with camelCase +public: + uint64_t m_handle; + +// Private member variables: m_ prefix with camelCase +private: + std::string m_functionName; + +// Methods: camelCase + void processMessage(); + +// Constants: UPPER_CASE +enum THREAD_TYPE { + FREERUNNING, + ONLY_MESSAGE +}; + +// Function parameters: camelCase +void setType(MESSAGE_TYPE messageType); + +} // namespace apra +``` + +#### Formatting + +- **Indentation**: Tabs (as per existing codebase) +- **Braces**: Opening brace on same line for functions, new line for classes +- **Line Length**: Prefer 80-100 characters, max 120 +- **Spaces**: Space after keywords, around operators + +Example: +```cpp +void MyClass::myFunction(int param1, bool param2) +{ + if (param2) + { + doSomething(param1); + } + else + { + doSomethingElse(); + } +} +``` + +#### Header Files + +```cpp +/* + * FileName.h + * + * Copyright (c) 2024 Apra Labs + * + * This file is part of ApraUtils. + * + * Licensed under the MIT License. + * See LICENSE file in the project root for full license information. + */ + +#ifndef INCLUDES_APRA_FILENAME_H_ +#define INCLUDES_APRA_FILENAME_H_ + +// System includes first +#include +#include + +// Local includes second +#include "models/Message.h" + +namespace apra +{ + +class ClassName +{ +public: + ClassName(); + virtual ~ClassName(); + +private: + int m_memberVariable; +}; + +} // namespace apra + +#endif /* INCLUDES_APRA_FILENAME_H_ */ +``` + +### Best Practices + +1. **RAII (Resource Acquisition Is Initialization)**: Use RAII for resource management +2. **Const Correctness**: Use `const` wherever appropriate +3. **Error Handling**: Use the GenericError/I2CError classes for error reporting +4. **Thread Safety**: Use Mutex and ScopeLock for thread-safe operations +5. **Memory Management**: Avoid raw pointers; prefer smart pointers when needed +6. **Comments**: Document complex logic; avoid obvious comments + +```cpp +// Good +// Calculate the average delay between I2C transactions to prevent bus saturation +uint64_t averageDelay = totalDelay / transactionCount; + +// Bad +// Set x to 5 +int x = 5; +``` + +## Commit Message Guidelines + +We follow conventional commit message format: + +### Format + +``` +(): + + + +