From 21b327a3007a493ecbae8ea62cab3f63ef87eeb2 Mon Sep 17 00:00:00 2001 From: alkonosst Date: Wed, 24 Jun 2026 14:26:09 -0400 Subject: [PATCH] ci: Add workflows, issue/PR templates and health files --- .github/CODE_OF_CONDUCT.md | 24 +++ .github/CONTRIBUTING.md | 164 +++++++++++++++++++++ .github/ISSUE_TEMPLATE/bug_report.yml | 91 ++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 + .github/ISSUE_TEMPLATE/feature_request.yml | 44 ++++++ .github/PULL_REQUEST_TEMPLATE.md | 22 +++ .github/release.yml | 22 +++ .github/workflows/create-release.yml | 32 ++++ .github/workflows/pio-ci.yml | 20 +++ .github/workflows/pr-label.yml | 19 +++ .gitignore | 3 + 11 files changed, 449 insertions(+) create mode 100644 .github/CODE_OF_CONDUCT.md create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/release.yml create mode 100644 .github/workflows/create-release.yml create mode 100644 .github/workflows/pio-ci.yml create mode 100644 .github/workflows/pr-label.yml diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..0af8d26 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,24 @@ +# Code of Conduct + +## Our pledge + +We are committed to providing a welcoming, friendly and harassment-free experience +for everyone who participates in this project, regardless of background or identity. + +## Our standard + +This project adopts the [Contributor Covenant](https://www.contributor-covenant.org/version/3/0/code_of_conduct/), +version 3.0, as its Code of Conduct. Please read the full text at the link above. + +In short: be respectful and constructive, assume good intent, and keep +interactions professional. Behavior that is abusive, harassing or otherwise +disrespectful is not acceptable. + +## Enforcement + +Instances of unacceptable behavior may be reported to the project maintainer at +**maximiliano.ramirezbravo@gmail.com**. All reports will be reviewed and handled +confidentially. + +This Code of Conduct is adapted from the Contributor Covenant, version 3.0, +available at https://www.contributor-covenant.org/version/3/0/code_of_conduct/. diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..31386cb --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,164 @@ +# Contributing + +Thanks for your interest in contributing! This guide covers the basics. + +## Reporting issues + +- Search [existing issues](../../issues) before opening a new one. +- Use the bug report or feature request template. + +## Development setup + +This is a PlatformIO library. You need [PlatformIO Core](https://docs.platformio.org/en/latest/core/installation/index.html) (or the VS Code extension). + +```bash +# Install PlatformIO Core (requires Python) +pip install -U platformio +``` + +## Running tests + +> [!IMPORTANT] +> Use the `*-test` environments for running unit tests with `pio test`. + +If you have a board, you can run the unit tests on it: + +```bash +# For example, for ESP32-S3: +pio test -e esp32-s3-test +``` + +Native unit tests run on the host (no board required): + +```bash +pio test -e native-test +``` + +The CI also runs the sanitizer and coverage environments: + +```bash +pio test -e native-san-test +pio test -e native-cov-test +``` + +## Verifying coverage + +> [!IMPORTANT] +> For this special case, you need to run `pio run` instead of `pio test`, because the coverage report generation is a custom target, not a test. + +The `native-cov-test` environment has a custom target that generates a coverage report in +`coverage/`, which you can view in your browser. + +To verify coverage, you need to install `gcovr`: + +```bash +pip install gcovr +``` + +Run the coverage report generation: + +```bash +pio run -e native-cov-test -t coverage +``` + +## Compiling examples + +> [!IMPORTANT] +> Use the `*-test` environments for compiling examples with `pio ci`. + +```bash +# Arduino example (replace with your board env) +pio ci -l . -c platformio.ini -e esp32-s3-test examples/ + +# Native example +pio ci -l . -c platformio.ini -e native-test examples/ +``` + +## Running examples + +> [!IMPORTANT] +> Use the `*-example` environments for running examples with `pio run`. + +Before running examples, you need to define the `EXAMPLE` environment variable to point to the example folder you want to run. For example, if you want to run the `examples/basic` example, you would set `EXAMPLE=examples/basic`. + +```bash +# Arduino example (replace with your board env) +# - Windows: +$env:EXAMPLE="examples/basic"; pio run -e esp32-s3-example -t upload -t monitor +# - Linux +export EXAMPLE="examples/basic"; pio run -e esp32-s3-example -t upload -t monitor + +# Native example +# - Windows: +$env:EXAMPLE="examples/basic"; pio run -e native-example -t exec +# - Linux +export EXAMPLE="examples/basic"; pio run -e native-example -t exec +``` + +## Code formatting + +Code is formatted with [clang-format](https://clang.llvm.org/docs/ClangFormat.html) using the +`.clang-format` file at the repo root. CI enforces this and **fails if any file is not formatted**, so +format your changes before opening a PR. + +> [!IMPORTANT] +> Use clang-format **17.0.6**, the exact version CI uses. Formatting output changes between major +> versions, so a different version may produce a diff CI rejects (or flag code that is actually fine). + +The easiest way to match the version is the pinned pip package: + +```bash +pip install clang-format==17.0.6 +``` + +Format all sources in place: + +```bash +clang-format -i $(git ls-files '*.c' '*.cc' '*.cpp' '*.cxx' '*.h' '*.hpp' '*.ino') +``` + +Alternatively, enable "format on save" in your editor pointed at clang-format 17.0.6. + +## Commit and PR conventions + +This project uses [Conventional Commits](https://www.conventionalcommits.org/). The **PR title** is what matters: it is used to auto-label the PR and to generate the release notes. + +Accepted types: `feat`, `fix`, `docs`, `refactor`, `chore`, `ci`. Append `!` (e.g. `feat!:`) for +breaking changes. + +Optionally, you can add a scope in parentheses after the type (e.g. `feat(mqtt):`). + +Examples: + +```md +# Add a new feature + +feat: add non-blocking publish API + +# Fix a bug with scope + +fix(reconnect): avoid heap fragmentation + +# Update documentation + +docs: document the timeout option + +# Refactor without changing the API + +refactor: simplify the connection logic + +# Breaking change by refactoring an API + +refactor!: rename begin() to start() + +# Breaking change by refactoring an API with scope + +refactor(api)!: rename begin() to start() +``` + +## Pull request process + +1. Fork the repo and create a branch from `main`. +2. Make your changes and keep them focused. +3. Format the code with clang-format, make sure tests pass and examples compile. +4. Open a PR with a Conventional Commit title and fill out the template. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..59a0f4b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,91 @@ +name: Bug report +description: Report a problem with the library. +title: "[bug]: " +labels: [bug] +body: + - type: markdown + attributes: + value: Thanks for taking the time to report a bug. Please fill out the sections below. + + - type: checkboxes + id: checks + attributes: + label: Preliminary checks + options: + - label: I searched existing issues and this bug has not been reported yet. + required: true + - label: I am using the latest released version of the library. + required: false + + - type: textarea + id: description + attributes: + label: Description + description: A clear and concise description of what the bug is. + validations: + required: true + + - type: input + id: library-version + attributes: + label: Library version + placeholder: e.g. 1.2.0 + validations: + required: true + + - type: input + id: board + attributes: + label: Board / MCU + placeholder: e.g. ESP32-S3-DevKitC-1, STM32F103C8, Native + validations: + required: true + + - type: dropdown + id: framework + attributes: + label: Framework + options: + - Arduino + - Native (host) + - Other + validations: + required: true + + - type: input + id: pio-version + attributes: + label: PlatformIO Core version + description: Output of "pio --version". + placeholder: e.g. 6.1.16 + validations: + required: false + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + description: A minimal sketch/example and the steps to trigger the bug. + placeholder: | + 1. Flash the sketch below. + 2. Open the serial monitor. + 3. ... + render: cpp + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + + - type: textarea + id: logs + attributes: + label: Logs / serial output + description: Paste any relevant build or runtime output. This is rendered as a code block. + render: shell + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..8f91e2c --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Questions and discussions + url: https://github.com/alkonosst/ByteFrame/discussions + about: Ask questions and discuss usage here instead of opening an issue. + - name: Support the project + url: https://ko-fi.com/alkonosst + about: If this library helps you, consider supporting its development. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..0dfbc73 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,44 @@ +name: Feature request +description: Suggest a new feature or improvement. +title: "[feature]: " +labels: [enhancement] +body: + - type: checkboxes + id: checks + attributes: + label: Preliminary checks + options: + - label: I searched existing issues and this feature has not been requested yet. + required: true + + - type: textarea + id: problem + attributes: + label: Problem / motivation + description: What problem does this feature solve? Why is it needed? + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed solution + description: Describe the API or behavior you would like to see. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Any alternative solutions or workarounds you have considered. + validations: + required: false + + - type: textarea + id: context + attributes: + label: Additional context + description: Add any other context, references or examples here. + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..36f5f59 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,22 @@ + + +## Description + + + +## Related issues + + + +## Checklist + +- [ ] The PR title follows Conventional Commits. +- [ ] The code is formatted with clang-format 17.0.6. +- [ ] Native unit tests pass (`pio test`). +- [ ] Examples compile. +- [ ] Documentation was updated if needed. diff --git a/.github/release.yml b/.github/release.yml new file mode 100644 index 0000000..6ed6b8d --- /dev/null +++ b/.github/release.yml @@ -0,0 +1,22 @@ +# Configuration for custom generating release notes based on PR labels. +# Combined with the PR labeling workflow, this allows to automatically generate +# release notes with categorized sections based on the PR labels. +changelog: + exclude: + labels: + - ignore-for-release + authors: + - dependabot + categories: + - title: Breaking Changes + labels: [breaking-change] + - title: New Features + labels: [feat] + - title: Bug Fixes + labels: [fix] + - title: Documentation + labels: [docs] + - title: Maintenance + labels: [chore, ci, refactor] + - title: Other Changes + labels: ["*"] diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml new file mode 100644 index 0000000..76e7059 --- /dev/null +++ b/.github/workflows/create-release.yml @@ -0,0 +1,32 @@ +# When a semantic version tag is pushed (e.g. v1.2.3): create the GitHub release and publish the +# package to the PlatformIO Registry. +# NOTE: no CI is run for release tags, so make sure to create a tag only after the CI has passed on the main branch. +name: Release + +on: + push: + tags: + - "v[0-9]+.[0-9]+.[0-9]+" + +permissions: + contents: read + +jobs: + release: + runs-on: ubuntu-latest + permissions: + contents: write + steps: + - uses: alkonosst/templates/.github/actions/release@v1 + + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + persist-credentials: false + - uses: alkonosst/templates/.github/actions/setup-python@v1 + - uses: alkonosst/templates/.github/actions/setup-pio@v1 + - uses: alkonosst/templates/.github/actions/pio-publish@v1 + with: + auth-token: ${{ secrets.PLATFORMIO_AUTH_TOKEN }} diff --git a/.github/workflows/pio-ci.yml b/.github/workflows/pio-ci.yml new file mode 100644 index 0000000..6f39734 --- /dev/null +++ b/.github/workflows/pio-ci.yml @@ -0,0 +1,20 @@ +# Run the reusable PlatformIO CI on every pull request and on pushes to main. +# Uploads coverage to Codecov (badge tracks main, PRs get the coverage diff). +name: CI + +on: + pull_request: + push: + branches: [main] + +permissions: + contents: read + pull-requests: write # allows the format-suggest job to post review suggestions + +jobs: + ci: + uses: alkonosst/templates/.github/workflows/reusable-pio-ci.yml@v1 + with: + upload-codecov: true + secrets: + codecov-token: ${{ secrets.CODECOV_TOKEN }} diff --git a/.github/workflows/pr-label.yml b/.github/workflows/pr-label.yml new file mode 100644 index 0000000..f141ede --- /dev/null +++ b/.github/workflows/pr-label.yml @@ -0,0 +1,19 @@ +# Auto-label each PR from its conventional commit title. +# Accepted types: +# - feat/fix/docs/chore/ci/refactor +# - breaking-change for "type!:" or "type(scope)!:" (scope is optional) +name: PR label + +# pull_request_target (not pull_request) so the job also gets a write token on PRs from forks. +# Safe here: the labeler only reads the PR title from the event payload and never checks out the +# fork's code. +on: + pull_request_target: + types: [opened, edited] + +permissions: + pull-requests: write + +jobs: + label: + uses: alkonosst/templates/.github/workflows/reusable-pr-label.yml@v1 diff --git a/.gitignore b/.gitignore index 29c3fed..78e1cdd 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,7 @@ +.claude .pio .vscode +build +coverage logs CLAUDE.md \ No newline at end of file