From 52e1f94878aa4319bccf73c4b35b35ff5a5b5a45 Mon Sep 17 00:00:00 2001 From: Srikanth Patchava Date: Thu, 10 Sep 2026 20:14:36 -0700 Subject: [PATCH] docs(governance): enforce linked issue policy Signed-off-by: Srikanth Patchava --- .github/PULL_REQUEST_TEMPLATE.md | 43 +++++++++++++++--------------- .github/workflows/linked-issue.yml | 16 +++++++++++ AGENTS.md | 36 +++++++++++++++++++++++++ docs/wiki/Development.md | 27 +++++++++++++++++++ docs/wiki/FAQ.md | 29 ++++++++++++++++++++ docs/wiki/Getting-Started.md | 28 +++++++++++++++++++ docs/wiki/Home.md | 22 +++++++++++++++ docs/wiki/Security.md | 13 +++++++++ docs/wiki/_Sidebar.md | 8 ++++++ 9 files changed, 200 insertions(+), 22 deletions(-) create mode 100644 .github/workflows/linked-issue.yml create mode 100644 docs/wiki/Development.md create mode 100644 docs/wiki/FAQ.md create mode 100644 docs/wiki/Getting-Started.md create mode 100644 docs/wiki/Home.md create mode 100644 docs/wiki/Security.md create mode 100644 docs/wiki/_Sidebar.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 6493a6b6..171d4afe 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,57 +2,56 @@ - ## Type of Change -- [ ] eat — New feature -- [ ] ix — Bug fix -- [ ] docs — Documentation only -- [ ] style — Formatting, no code change -- [ ] efactor — Code restructuring without behavior change -- [ ] est — Add or fix tests -- [ ] uild — Build system or dependency changes -- [ ] ci — CI/CD pipeline changes -- [ ] perf — Performance improvement +- [ ] feat - New feature +- [ ] fix - Bug fix +- [ ] docs - Documentation only +- [ ] style - Formatting, no code change +- [ ] refactor - Code restructuring without behavior change +- [ ] test - Add or fix tests +- [ ] build - Build system or dependency changes +- [ ] ci - CI/CD pipeline changes +- [ ] perf - Performance improvement ## Changes -- -- +- +- ## Testing -- [ ] Unit tests pass (ctest --test-dir build --output-on-failure) +- [ ] Unit tests pass (`ctest --test-dir build --output-on-failure`) - [ ] Integration tests pass - [ ] Manual testing performed - [ ] New tests added for new functionality ## Pre-Submission Checklist -- [ ] Code compiles without warnings (-Wall -Wextra -Werror for C) +- [ ] Code compiles without warnings (`-Wall -Wextra -Werror` for C) - [ ] All existing tests pass - [ ] New tests added for new functionality - [ ] Documentation updated if API changed -- [ ] Commit messages follow (): convention -- [ ] Branch is rebased on latest master +- [ ] Commit messages follow the `(): ` convention +- [ ] Branch is rebased on latest `master` +- [ ] This PR links a real issue in this repository with a closing keyword -## Related Issues +## Related Issue - + +Fixes # ## Screenshots / Logs - - + ## Additional Notes - - + diff --git a/.github/workflows/linked-issue.yml b/.github/workflows/linked-issue.yml new file mode 100644 index 00000000..973e19e0 --- /dev/null +++ b/.github/workflows/linked-issue.yml @@ -0,0 +1,16 @@ +name: Linked issue policy + +on: + pull_request_target: + types: [opened, edited, reopened, synchronize] + +permissions: + contents: read + issues: read + pull-requests: read + +jobs: + policy: + uses: embeddedos-org/.github/.github/workflows/linked-issue-policy.yml@92cb596c773496ec4df76717e8acf0e6b7700f73 + with: + policy_ref: 92cb596c773496ec4df76717e8acf0e6b7700f73 diff --git a/AGENTS.md b/AGENTS.md index 93f33f5a..0532f54d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,42 @@ One rule is structural rather than stylistic: **whoever implements does not approve.** Review is a separate role because self-review reliably misses the thing the implementer already believes is correct. +## Repository map + +- `ebuild/` is the Python package. Keep CLI wiring in `ebuild/cli/`, backend + selection and execution in `ebuild/build/`, dependency and package behavior + in `ebuild/deps/` and `ebuild/packages/`, and image or firmware workflows in + `ebuild/system/` and `ebuild/firmware/`. +- `core/` contains vendored native EoS and eBoot components. Changes there need + the component's CMake tests in addition to the Python suite. +- `recipes/`, `layers/`, `hardware/`, and `templates/` are user-facing build + inputs. Preserve their schemas and add a focused parser, resolver, or + generated-output test when behavior changes. +- `docs/` is the MkDocs source. `docs/wiki/` mirrors the six published GitHub + Wiki pages; keep those pages aligned when their shared guidance changes. +- `tests/ebuild/` and `tests/unit/` cover the Python tool, while + `tests/functional/`, `tests/performance/`, and native `core/**/tests/` cover + broader behavior. Do not use `tests_backup/` as the validation target. + +## Working in this repository + +1. Read `README.md`, `CONTRIBUTING.md`, and the nearest component files before + editing. Keep changes within the requested subsystem. +2. Install the Python development environment with + `python -m pip install -e ".[dev]"` when dependencies are not already + available. +3. Run focused tests for the changed behavior, then run + `python -m pytest tests/ -v --tb=short` when the environment supports the + full suite. +4. Run `ruff check .` for Python changes. For native changes, configure with + `cmake -S . -B build -DEOS_BUILD_TESTS=ON`, build with `cmake --build build`, + and run `ctest --test-dir build --output-on-failure`. +5. Validate changed YAML and Markdown with the repository tooling, and always + run `git diff --check` before committing. +6. Follow the DCO and conventional commit requirements in `CONTRIBUTING.md`. + Pull requests must use a closing keyword such as `Fixes #123` for a real + issue in this repository. + ## Planner — [.ai/planner.md](./.ai/planner.md) - Understand the request. diff --git a/docs/wiki/Development.md b/docs/wiki/Development.md new file mode 100644 index 00000000..819d78d3 --- /dev/null +++ b/docs/wiki/Development.md @@ -0,0 +1,27 @@ +# Development + +## Contribution source of truth + +[CONTRIBUTING](https://github.com/embeddedos-org/ebuild/blob/master/CONTRIBUTING.md) + +Before proposing a change, also review the [README](https://github.com/embeddedos-org/ebuild/blob/master/README.md). Keep changes scoped, add tests appropriate to the affected behavior, and follow the repository's current automation and review requirements. + +## Build and dependency inputs found + +`CMakeLists.txt`, `Dockerfile`, `core/eboot/CMakeLists.txt`, `core/eboot/requirements.txt`, `core/eboot/tests/CMakeLists.txt`, `core/eos/CMakeLists.txt`, `core/eos/backends/CMakeLists.txt`, `core/eos/cmd/eos/CMakeLists.txt`, `core/eos/core/CMakeLists.txt`, `core/eos/debug/CMakeLists.txt`, `core/eos/drivers/devicetree/CMakeLists.txt`, `core/eos/examples/ble-sensor/CMakeLists.txt`, and 55 more. + +## Tests found in the default-branch tree + +`core/eboot/tests/CMakeLists.txt`, `core/eboot/tests/unit/test_board_config.c`, `core/eboot/tests/unit/test_board_registry.c`, `core/eboot/tests/unit/test_bootctl.c`, `core/eboot/tests/unit/test_crypto.c`, `core/eboot/tests/unit/test_device_table.c`, `core/eboot/tests/unit/test_multicore.c`, `core/eboot/tests/unit/test_runtime_svc.c`, `core/eos/tests/CMakeLists.txt`, `core/eos/tests/mocks/lvgl.h`, `core/eos/tests/test_config.c`, `core/eos/tests/test_crypto.c`, and 132 more. + +## Documented test commands + +These commands are reproduced from the inspected root README or contributing guide: + +```bash +pytest # configuration in pytest.ini +``` + +## Verification baseline + +This inventory comes from `master` at [`8b623d5786b5`](https://github.com/embeddedos-org/ebuild/commit/8b623d5786b5f841823f92a5506269f1e155a0f1) and found 144 test-related paths among 1210 files. Re-check the source tree when that commit is no longer current. diff --git a/docs/wiki/FAQ.md b/docs/wiki/FAQ.md new file mode 100644 index 00000000..e7fd519a --- /dev/null +++ b/docs/wiki/FAQ.md @@ -0,0 +1,29 @@ +# FAQ + +## What is `ebuild`? + +ebuild — Unified Embedded Build System + +## Which branch does this wiki describe? + +The latest publication inspected `master` at [`8b623d5786b5`](https://github.com/embeddedos-org/ebuild/commit/8b623d5786b5f841823f92a5506269f1e155a0f1). + +## Where are setup instructions? + +Start with the [README](https://github.com/embeddedos-org/ebuild/blob/master/README.md), then use [Getting Started](Getting-Started) for a concise map of the checked-in project inputs. + +## How do I contribute? + +Use the [CONTRIBUTING](https://github.com/embeddedos-org/ebuild/blob/master/CONTRIBUTING.md) and the evidence-backed inventory on [Development](Development). If no root contributing guide exists, inspect the README, repository automation, and recent accepted changes before proposing work. + +## How do I run tests? + +[Development](Development) lists the 144 test-related paths found in the inspected tree and reproduces recognized test commands only when they appear in the root README or contributing guide. + +## How do I report a security issue? + +Follow [Security](Security). The source-tree policy status for this publication is: [SECURITY](https://github.com/embeddedos-org/ebuild/blob/master/SECURITY.md) + +## Is the wiki authoritative? + +No. The [embeddedos-org/ebuild source tree](https://github.com/embeddedos-org/ebuild) is authoritative. The wiki is a repository-specific guide to that source. diff --git a/docs/wiki/Getting-Started.md b/docs/wiki/Getting-Started.md new file mode 100644 index 00000000..6ed4f6b5 --- /dev/null +++ b/docs/wiki/Getting-Started.md @@ -0,0 +1,28 @@ +# Getting Started + +## Repository purpose + +ebuild — Unified Embedded Build System + +## First steps + +1. Read the [README](https://github.com/embeddedos-org/ebuild/blob/master/README.md) for the project's supported setup and usage path. +2. Clone the repository and enter its directory: + +```bash +git clone https://github.com/embeddedos-org/ebuild.git +cd ebuild +``` + +3. Check the root project inputs below before installing dependencies or selecting a build tool. +4. Review [Development](Development) before changing code, and [Security](Security) before reporting a vulnerability. + +## Root project inputs + +- `CMakeLists.txt`: CMake build definition. +- `Dockerfile`: Container build definition. +- `pyproject.toml`: Python project manifest. + +## Scope note + +The default branch inspected for this page was `master` at [`8b623d5786b5`](https://github.com/embeddedos-org/ebuild/commit/8b623d5786b5f841823f92a5506269f1e155a0f1). This page intentionally does not invent a universal build command when the repository's own documentation does not provide one. diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 00000000..7c684569 --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,22 @@ +# ebuild + +ebuild — Unified Embedded Build System + +This wiki is a maintained navigation layer for [embeddedos-org/ebuild](https://github.com/embeddedos-org/ebuild). Source files on the `master` default branch remain authoritative for code, commands, policies, and release behavior. + +## Start here + +- [Getting Started](Getting-Started) explains how to orient yourself using the repository's checked-in entry points. +- [Development](Development) records the build manifests, contribution guidance, and tests found during the latest source inspection. +- [Security](Security) points to the repository's vulnerability-reporting policy. +- [FAQ](FAQ) answers common repository-specific navigation questions. + +## Source snapshot + +- Default branch: `master` +- Inspected source commit: [`8b623d5786b5`](https://github.com/embeddedos-org/ebuild/commit/8b623d5786b5f841823f92a5506269f1e155a0f1) +- Root project overview: [README](https://github.com/embeddedos-org/ebuild/blob/master/README.md) +- Contribution guidance: [CONTRIBUTING](https://github.com/embeddedos-org/ebuild/blob/master/CONTRIBUTING.md) +- Security policy: [SECURITY](https://github.com/embeddedos-org/ebuild/blob/master/SECURITY.md) + +The wiki was generated from repository content, but it does not replace that content. If a wiki statement and the source tree disagree, follow the source tree and open a documentation correction. diff --git a/docs/wiki/Security.md b/docs/wiki/Security.md new file mode 100644 index 00000000..84037692 --- /dev/null +++ b/docs/wiki/Security.md @@ -0,0 +1,13 @@ +# Security + +## Reporting vulnerabilities + +The repository has a root [SECURITY](https://github.com/embeddedos-org/ebuild/blob/master/SECURITY.md). Follow that policy for supported versions, reporting channels, disclosure expectations, and response details. + +Do not publish suspected vulnerabilities in a public issue unless the policy explicitly directs you to do so. Provide a clear description, affected versions or commits, reproduction details, impact, and any known mitigation through the private channel named by the policy. + +## Evidence + +- Repository: [embeddedos-org/ebuild](https://github.com/embeddedos-org/ebuild) +- Inspected branch: `master` +- Inspected commit: [`8b623d5786b5`](https://github.com/embeddedos-org/ebuild/commit/8b623d5786b5f841823f92a5506269f1e155a0f1) diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md new file mode 100644 index 00000000..2b1378c7 --- /dev/null +++ b/docs/wiki/_Sidebar.md @@ -0,0 +1,8 @@ +**ebuild Wiki** + +- [Home](Home) +- [Getting Started](Getting-Started) +- [Development](Development) +- [Security](Security) +- [FAQ](FAQ) +- [Source Repository](https://github.com/embeddedos-org/ebuild)