diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 6493a6b..1f8f556 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,58 +1,52 @@ -## Summary - - +## Closing Issue + -## Type of Change +Fixes # - +> Replace the placeholder above with a real issue number before requesting review. The exact trusted automation identities listed in `governance/repositories.json` are exempt. -- [ ] 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 +## Summary -## Changes + - +## Type of Change -- -- + -## Testing +- [ ] feat - New feature +- [ ] fix - Bug fix +- [ ] docs - Documentation only +- [ ] style - Formatting, no behavior 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 -- [ ] 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) -- [ ] 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 +## Validation -## Related Issues + - +- [ ] Relevant Playwright, Python, link, and markup checks pass. +- [ ] Manual browser testing was performed when site behavior changed. +- [ ] No secrets, credentials, internal hostnames, or production data are included. +- [ ] User-facing documentation is updated when behavior changes. +## Risk and Rollout -## Screenshots / Logs + - +## Screenshots or Logs + ## Additional Notes - - + diff --git a/.github/workflows/linked-issue.yml b/.github/workflows/linked-issue.yml new file mode 100644 index 0000000..973e19e --- /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 93f33f5..e2b22cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,98 +1,51 @@ - -# Agent Responsibilities +# Repository Agent Guide -Each role owns a slice of the work and does only that slice. Full briefs are in -[.ai/](./.ai/). These are responsibilities, not a required agent count — one -agent may hold several roles on a small change. Split when the roles need -genuinely different context, not by default. +## Scope -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. +This repository is the source for the EmbeddedOS GitHub Pages site at +. It is a static site built from HTML, CSS, +and vanilla JavaScript; there is no application build step. -## Planner — [.ai/planner.md](./.ai/planner.md) +## Structure -- Understand the request. -- Break work into tasks. -- Assign work. +- Root `*.html` files are the primary public pages. +- `docs/`, `stacks/`, `eApps/`, and `downloads/` contain additional site pages. +- `docs/wiki/` mirrors the six published repository Wiki pages in source control. +- `style.css` contains global styles. +- `js/site-chrome.js` is the shared source of truth for navigation and footer + markup. Update it when changing site-wide community links. +- `tests/` contains Playwright and Python test suites. +- `.github/workflows/` contains CI and deployment automation. -## Architect — [.ai/architect.md](./.ai/architect.md) +## Working Safely -- Design structure. -- Choose patterns. -- Own dependencies, scalability and maintainability. +- Start changes from the protected `master` branch and work on a feature branch. +- Keep edits focused. Do not modify generated artifacts or unrelated content. +- Preserve the static-site structure and existing accessibility attributes. +- Do not add secrets, credentials, internal hostnames, or production data. +- Treat the checked-in files as authoritative. The GitHub Wiki is a published + navigation layer, not the source of truth for code or policy. +- Pull requests must use a closing keyword for an issue in this repository, + such as `Fixes #123`. -## Backend — [.ai/backend.md](./.ai/backend.md) +## Validation -- APIs -- Database -- Business logic +Install dependencies with `npm install` when needed, then serve the repository +root with `npm run serve`. Run checks appropriate to the change: -## Frontend — [.ai/frontend.md](./.ai/frontend.md) +```bash +npm run test:chromium +npm run test:links +npm run lint:html +``` -- UI -- Components -- Accessibility +For documentation and workflow changes, also validate YAML syntax, Markdown +links, and relative file targets. Review `git diff --check` before committing. +Document every command run and any check that could not be completed in the +pull request. -## Testing — [.ai/testing.md](./.ai/testing.md) +## Contributions -- Unit tests -- Integration tests -- Regression tests - -## Security — [.ai/security.md](./.ai/security.md) - -- Authentication and authorization -- Validation -- Secrets -- Dependency review - -## Performance — [.ai/performance.md](./.ai/performance.md) - -- Profiling -- Optimization -- Scalability - -## Reviewer — [.ai/reviewer.md](./.ai/reviewer.md) - -- Final review -- Verify requirements -- Merge findings - -## Documentation — [.ai/docs.md](./.ai/docs.md) - -- README -- API docs -- Changelog -- Migration and architecture notes - -## Release — [.ai/release.md](./.ai/release.md) - -- Release notes -- Deployment preparation -- Rollback guidance - ---- - -## Switching roles - -Switch when the task changes domain, when specialist knowledge is required, -when independent review is required, or when the context has grown past what -one agent can hold accurately. Every switch runs the protocol in -[HANDOFF.md](./HANDOFF.md). - -## Finding work that is not yours - -You will. The rule is: **record it, do not absorb it, do not drop it.** - -| What you found | Do | -|----------------|-----| -| A defect unrelated to your task | Note it in [TASKS.md](./TASKS.md) and keep going. | -| A defect your change would sit on top of | Stop; say it blocks you; propose fixing it as its own task. | -| A security issue | Report immediately, whatever role you hold. This one never waits for a handoff. | -| A design decision missing from the plan | Return to the architect rather than deciding it inside an implementation. | -| Work that belongs to a role nobody assigned | Say so. An unowned task is how requirements go missing. | - -Silently fixing something outside your task makes the diff unreviewable. -Silently ignoring it means nobody ever looks again. Neither is acceptable; the -note is what makes the difference. +Follow [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and the +pull request template. Report suspected vulnerabilities through the private +channel described in `SECURITY.md`, never through a public issue. diff --git a/README.md b/README.md index 6f4fdab..68f9a24 100644 --- a/README.md +++ b/README.md @@ -31,11 +31,22 @@ js/ animations.js, ebot-chat.js, search.js, site-chrome.js stacks/ Technology stack pages (eai-edge.html, index.html) eApps/ eApps index + icons downloads/ Downloads index -docs/ Component docs (ebrowser, ebuild, eai, eos, ...) + book/ +docs/ Component docs (ebrowser, ebuild, eai, eos, ...) + book/ + wiki/ style.css Global styles sitemap.xml, robots.txt, _headers, favicon.svg, og-image.png ``` +## Community + +- [Wiki](https://github.com/embeddedos-org/embeddedos-org.github.io/wiki) +- [Discussions](https://github.com/embeddedos-org/embeddedos-org.github.io/discussions) +- [Issues](https://github.com/embeddedos-org/embeddedos-org.github.io/issues) +- [Projects](https://github.com/orgs/embeddedos-org/projects) +- [Agent guide](AGENTS.md) + +The six published Wiki pages are also preserved in [`docs/wiki/`](docs/wiki/Home.md) +so their content can be reviewed and maintained with the site source. + ## Develop Serve the site locally (static file server on port 8080): diff --git a/docs/wiki/Development.md b/docs/wiki/Development.md new file mode 100644 index 0000000..82fe3e5 --- /dev/null +++ b/docs/wiki/Development.md @@ -0,0 +1,31 @@ +# Development + +## Contribution source of truth + +[CONTRIBUTING](https://github.com/embeddedos-org/embeddedos-org.github.io/blob/master/CONTRIBUTING.md) + +Before proposing a change, also review the [README](https://github.com/embeddedos-org/embeddedos-org.github.io/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 + +`package.json`. + +## Tests found in the default-branch tree + +`tests/__init__.py`, `tests/acceptance/__init__.py`, `tests/acceptance/test_acceptance.py`, `tests/accessibility.spec.js`, `tests/functional/__init__.py`, `tests/functional/test_functional_e2e.py`, `tests/integration/__init__.py`, `tests/integration/test_integration.py`, `tests/links.spec.js`, `tests/performance.spec.js`, `tests/performance/__init__.py`, `tests/performance/test_performance_benchmarks.py`, and 16 more. + +## Documented test commands + +These commands are reproduced from the inspected root README or contributing guide: + +```bash +npm test # all Playwright specs +``` + +```bash +npm test +``` + +## Verification baseline + +This inventory comes from `master` at [`2899ddc0ceea`](https://github.com/embeddedos-org/embeddedos-org.github.io/commit/2899ddc0ceea5d275750f737452febedc1666292) and found 28 test-related paths among 144 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 0000000..2a1920b --- /dev/null +++ b/docs/wiki/FAQ.md @@ -0,0 +1,29 @@ +# FAQ + +## What is `embeddedos-org.github.io`? + +EmbeddedOS Website (GitHub Pages) + +## Which branch does this wiki describe? + +The latest publication inspected `master` at [`2899ddc0ceea`](https://github.com/embeddedos-org/embeddedos-org.github.io/commit/2899ddc0ceea5d275750f737452febedc1666292). + +## Where are setup instructions? + +Start with the [README](https://github.com/embeddedos-org/embeddedos-org.github.io/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/embeddedos-org.github.io/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 28 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/embeddedos-org.github.io/blob/master/SECURITY.md) + +## Is the wiki authoritative? + +No. The [embeddedos-org/embeddedos-org.github.io source tree](https://github.com/embeddedos-org/embeddedos-org.github.io) 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 0000000..668f1b8 --- /dev/null +++ b/docs/wiki/Getting-Started.md @@ -0,0 +1,26 @@ +# Getting Started + +## Repository purpose + +EmbeddedOS Website (GitHub Pages) + +## First steps + +1. Read the [README](https://github.com/embeddedos-org/embeddedos-org.github.io/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/embeddedos-org.github.io.git +cd embeddedos-org.github.io +``` + +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 + +- `package.json`: Node.js package manifest. + +## Scope note + +The default branch inspected for this page was `master` at [`2899ddc0ceea`](https://github.com/embeddedos-org/embeddedos-org.github.io/commit/2899ddc0ceea5d275750f737452febedc1666292). 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 0000000..339ede5 --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,22 @@ +# embeddedos-org.github.io + +EmbeddedOS Website (GitHub Pages) + +This wiki is a maintained navigation layer for [embeddedos-org/embeddedos-org.github.io](https://github.com/embeddedos-org/embeddedos-org.github.io). 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: [`2899ddc0ceea`](https://github.com/embeddedos-org/embeddedos-org.github.io/commit/2899ddc0ceea5d275750f737452febedc1666292) +- Root project overview: [README](https://github.com/embeddedos-org/embeddedos-org.github.io/blob/master/README.md) +- Contribution guidance: [CONTRIBUTING](https://github.com/embeddedos-org/embeddedos-org.github.io/blob/master/CONTRIBUTING.md) +- Security policy: [SECURITY](https://github.com/embeddedos-org/embeddedos-org.github.io/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 0000000..f3d70e5 --- /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/embeddedos-org.github.io/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/embeddedos-org.github.io](https://github.com/embeddedos-org/embeddedos-org.github.io) +- Inspected branch: `master` +- Inspected commit: [`2899ddc0ceea`](https://github.com/embeddedos-org/embeddedos-org.github.io/commit/2899ddc0ceea5d275750f737452febedc1666292) diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md new file mode 100644 index 0000000..8ab32c1 --- /dev/null +++ b/docs/wiki/_Sidebar.md @@ -0,0 +1,8 @@ +**embeddedos-org.github.io Wiki** + +- [Home](Home) +- [Getting Started](Getting-Started) +- [Development](Development) +- [Security](Security) +- [FAQ](FAQ) +- [Source Repository](https://github.com/embeddedos-org/embeddedos-org.github.io) diff --git a/js/site-chrome.js b/js/site-chrome.js index 50b374f..88f66f3 100644 --- a/js/site-chrome.js +++ b/js/site-chrome.js @@ -105,10 +105,11 @@ '
', '

Community

', '', '
',