diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 6493a6b..df0c164 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,58 +1,69 @@ +# Pull Request + +## Closing issue + + + +Fixes #123 + +> Replace `#123` with the real issue number before requesting review. + ## Summary - ## 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 `(): ` convention +- [ ] Branch is rebased on latest `master` ## Related Issues - - + ## Screenshots / 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..82f115b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,98 +1,43 @@ - -# Agent Responsibilities - -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. - -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. - -## Planner — [.ai/planner.md](./.ai/planner.md) - -- Understand the request. -- Break work into tasks. -- Assign work. - -## Architect — [.ai/architect.md](./.ai/architect.md) - -- Design structure. -- Choose patterns. -- Own dependencies, scalability and maintainability. - -## Backend — [.ai/backend.md](./.ai/backend.md) - -- APIs -- Database -- Business logic - -## Frontend — [.ai/frontend.md](./.ai/frontend.md) - -- UI -- Components -- Accessibility - -## Testing — [.ai/testing.md](./.ai/testing.md) - -- 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. +# Repository Guidance for Agents + +## Scope and architecture + +eBrowser is a C11 browser for constrained and desktop targets. Core browser +modules live in `src/`, public interfaces in `include/ebrowser/`, platform +abstractions in `platform/`, and target ports in `port/eos/`, `port/sdl2/`, and +`port/web/`. Security and network changes require particular care in +`src/security/`, `src/network/`, `src/privacy/`, and `src/engine/`. Companion +surfaces live in `web-app/`, `mobile/`, `extension/`, and `enterprise/`. + +Follow the specialist role briefs in [`.ai/`](./.ai/) and the handoff protocol in +[`HANDOFF.md`](./HANDOFF.md). The implementer must not act as the approving +reviewer. Keep public headers and their implementations synchronized, and avoid +mixing unrelated browser-engine, UI, and companion-app changes. + +## Build and validation + +- Configure native tests with `cmake -B build -DBUILD_TESTING=ON`. +- Build with `cmake --build build`. +- Run native tests with `ctest --test-dir build --output-on-failure`. +- Run the Python suites with `python run_all_tests.py`. +- For target-specific work, validate the affected EoS, SDL2, WebAssembly, + mobile, or web-app path using its local manifest and workflow. +- For parser, URL, cache, cookie, TLS, or sandbox changes, add focused regression + tests including malformed input and failure paths. + +Do not claim a target was tested when its toolchain was unavailable. Record the +missing SDK or runtime explicitly. + +## Change discipline + +Preserve C11 portability, warning-clean builds, ownership rules, and bounds +checks. Never weaken TLS verification, origin/referrer handling, sandboxing, or +input validation to make a test pass. Do not commit build directories, fetched +dependencies, credentials, certificates, or generated packages. + +Every human-authored pull request must use a GitHub-recognized closing keyword +for an issue in this repository, for example `Fixes #123`. Cross-repository +issues and plain issue mentions do not satisfy the linked-issue policy. Follow +[`.github/PULL_REQUEST_TEMPLATE.md`](./.github/PULL_REQUEST_TEMPLATE.md), and +keep the published Wiki snapshot in [`docs/wiki/`](./docs/wiki/) synchronized +when Wiki content changes. diff --git a/docs/wiki/Development.md b/docs/wiki/Development.md new file mode 100644 index 0000000..8ebba0d --- /dev/null +++ b/docs/wiki/Development.md @@ -0,0 +1,51 @@ +# Development + +## Contribution source of truth + +[CONTRIBUTING](https://github.com/embeddedos-org/eBrowser/blob/master/CONTRIBUTING.md) + +Before proposing a change, also review the [README](https://github.com/embeddedos-org/eBrowser/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`, `enterprise/docker/Dockerfile`, `enterprise/docker/docker-compose.yml`, `fuzz/CMakeLists.txt`, `mobile/package.json`, `platform/CMakeLists.txt`, `port/CMakeLists.txt`, `src/browser/CMakeLists.txt`, `src/engine/CMakeLists.txt`, `src/extensions/CMakeLists.txt`, `src/input/CMakeLists.txt`, and 16 more. + +## Tests found in the default-branch tree + +`tests/CMakeLists.txt`, `tests/__init__.py`, `tests/benchmark.c`, `tests/functional/__init__.py`, `tests/functional/test_functional_e2e.py`, `tests/http2_server.c`, `tests/load_test.c`, `tests/load_test_combined.c`, `tests/perf_regression.c`, `tests/performance/__init__.py`, `tests/performance/test_performance_benchmarks.py`, `tests/simulation/__init__.py`, and 25 more. + +## Documented test commands + +These commands are reproduced from the inspected root README or contributing guide: + +```bash +cmake -B build -DCMAKE_BUILD_TYPE=Release +``` + +```bash +cmake --build build -j +``` + +```bash +cmake -B build -DBUILD_TESTING=ON +``` + +```bash +ctest --test-dir build +``` + +```bash +cmake -B build +``` + +```bash +cmake --build build +``` + +```bash +ctest --test-dir build --output-on-failure +``` + +## Verification baseline + +This inventory comes from `master` at [`bb37c5bc4171`](https://github.com/embeddedos-org/eBrowser/commit/bb37c5bc41712c36eb5432d0699cbdb0bfec806e) and found 37 test-related paths among 313 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..15673f6 --- /dev/null +++ b/docs/wiki/FAQ.md @@ -0,0 +1,29 @@ +# FAQ + +## What is `eBrowser`? + +eBrowser — Embedded Web Browser + +## Which branch does this wiki describe? + +The latest publication inspected `master` at [`bb37c5bc4171`](https://github.com/embeddedos-org/eBrowser/commit/bb37c5bc41712c36eb5432d0699cbdb0bfec806e). + +## Where are setup instructions? + +Start with the [README](https://github.com/embeddedos-org/eBrowser/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/eBrowser/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 37 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/eBrowser/blob/master/SECURITY.md) + +## Is the wiki authoritative? + +No. The [embeddedos-org/eBrowser source tree](https://github.com/embeddedos-org/eBrowser) 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..a560547 --- /dev/null +++ b/docs/wiki/Getting-Started.md @@ -0,0 +1,27 @@ +# Getting Started + +## Repository purpose + +eBrowser — Embedded Web Browser + +## First steps + +1. Read the [README](https://github.com/embeddedos-org/eBrowser/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/eBrowser.git +cd eBrowser +``` + +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. + +## Scope note + +The default branch inspected for this page was `master` at [`bb37c5bc4171`](https://github.com/embeddedos-org/eBrowser/commit/bb37c5bc41712c36eb5432d0699cbdb0bfec806e). 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..1c8a95b --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,22 @@ +# eBrowser + +eBrowser — Embedded Web Browser + +This wiki is a maintained navigation layer for [embeddedos-org/eBrowser](https://github.com/embeddedos-org/eBrowser). 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: [`bb37c5bc4171`](https://github.com/embeddedos-org/eBrowser/commit/bb37c5bc41712c36eb5432d0699cbdb0bfec806e) +- Root project overview: [README](https://github.com/embeddedos-org/eBrowser/blob/master/README.md) +- Contribution guidance: [CONTRIBUTING](https://github.com/embeddedos-org/eBrowser/blob/master/CONTRIBUTING.md) +- Security policy: [SECURITY](https://github.com/embeddedos-org/eBrowser/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..669fe8e --- /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/eBrowser/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/eBrowser](https://github.com/embeddedos-org/eBrowser) +- Inspected branch: `master` +- Inspected commit: [`bb37c5bc4171`](https://github.com/embeddedos-org/eBrowser/commit/bb37c5bc41712c36eb5432d0699cbdb0bfec806e) diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md new file mode 100644 index 0000000..cc9b853 --- /dev/null +++ b/docs/wiki/_Sidebar.md @@ -0,0 +1,8 @@ +**eBrowser Wiki** + +- [Home](Home) +- [Getting Started](Getting-Started) +- [Development](Development) +- [Security](Security) +- [FAQ](FAQ) +- [Source Repository](https://github.com/embeddedos-org/eBrowser)