From d0e332d36173e1053364c993fa7d8124172d877e Mon Sep 17 00:00:00 2001 From: Leonardo Araujo dos Santos Date: Sun, 5 Jul 2026 09:30:36 -0300 Subject: [PATCH] docs: add OSS governance files, versioning policy, refresh roadmap Tier-2 project hygiene so the repo is approachable and trustworthy for outside contributors and users. Governance / community health: - CONTRIBUTING.md: setup, the spec-first OpenSpec workflow, what a mergeable PR looks like (tests + regression test for bugs, green CI, docs/specs in sync, readable low-complexity code), and numerical-correctness expectations. - SECURITY.md: private vulnerability reporting (GitHub advisories / email), supported-versions table, scope. - CODE_OF_CONDUCT.md: Contributor Covenant 2.1. - CHANGELOG.md: Keep a Changelog format; [Unreleased] + the 0.0.1 release. - .github issue forms (bug / feature), issue chooser config (security + discussions links), and a pull-request template. Trust / clarity: - README: a "Versioning & API stability" section (pre-1.0, SOVERSION-pinned C ABI) and links to the new governance files. - docs/roadmap.md: mark M1/M2/M4 done and M3 done-except-SYCL (they had shipped but were unmarked); fix the broken bootstrap-change link; add the real remaining work (SYCL, mobile + bindings GA, pip wheel, drag/lift, Conan/vcpkg). openspec validate --all --strict passes (14/14). --- .github/ISSUE_TEMPLATE/bug_report.yml | 49 +++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 +++ .github/ISSUE_TEMPLATE/feature_request.yml | 37 ++++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 21 +++++++ CHANGELOG.md | 48 +++++++++++++++ CODE_OF_CONDUCT.md | 56 ++++++++++++++++++ CONTRIBUTING.md | 69 ++++++++++++++++++++++ README.md | 10 +++- SECURITY.md | 37 ++++++++++++ docs/roadmap.md | 48 +++++++++------ 10 files changed, 364 insertions(+), 19 deletions(-) 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 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..24eaeb8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,49 @@ +name: Bug report +description: Report incorrect behavior, a crash, or a numerical discrepancy +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for the report. For **security** issues, do not file here — see + [SECURITY.md](https://github.com/CyberdyneCorp/Cyberfluids/blob/main/SECURITY.md). + - type: textarea + id: what-happened + attributes: + label: What happened? + description: What went wrong, and what did you expect instead? + placeholder: The 3D wind tunnel diverges after ~N steps at Re=... + validations: + required: true + - type: textarea + id: repro + attributes: + label: Steps to reproduce + description: A minimal case — grid size, parameters, obstacle/mesh, backend, and how you drove it (C++, Python, Swift, or `just`). + placeholder: | + just bench 64 32 32 100 + # or a code snippet / Python script + validations: + required: true + - type: input + id: backend + attributes: + label: Backend + placeholder: CPU (par_unseq) / CUDA / OpenCL / Metal + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment + description: OS, compiler + version, CMake version, GPU + driver (if relevant), commit/tag. + placeholder: | + Ubuntu 24.04, GCC 13.3, CMake 3.28, RTX 5060 (driver 580.95), commit abc1234 + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs / output + description: Relevant build or run output (paste as text or attach files). + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..e8bd8c9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Security vulnerability + url: https://github.com/CyberdyneCorp/Cyberfluids/security/advisories/new + about: Report security issues privately — please do not open a public issue. + - name: Question / discussion + url: https://github.com/CyberdyneCorp/Cyberfluids/discussions + about: Ask usage questions or discuss ideas before filing a feature request. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..30a66f5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,37 @@ +name: Feature request +description: Propose a new capability (physics model, backend, binding, tooling) +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: The use case or limitation motivating the request. + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed capability + description: What you'd like Cyberfluids to do. Larger features are developed spec-first with OpenSpec — see CONTRIBUTING.md. + validations: + required: true + - type: dropdown + id: area + attributes: + label: Area + options: + - Physics / dynamics + - Boundary conditions / geometry + - Backend (CPU / CUDA / OpenCL / Metal / SYCL) + - Language bindings (Python / Swift) + - Build / packaging / tooling + - Documentation + - Other + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Other approaches or existing workarounds, if any. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..4e58c95 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,21 @@ + + +## Summary + + + +## Related + + + +## Checklist + +- [ ] Tests added/updated; **bug fixes include a regression test** that fails before the fix. +- [ ] `openspec validate --all --strict` passes (spec-first for medium/large features). +- [ ] Docs and `openspec/specs/` updated where behavior changed — no claim left contradicting the code. +- [ ] CI is green (Linux + macOS + OpenSpec). +- [ ] For physics changes: the Palabos-oracle / GPU-vs-CPU tests still pass. + +## Notes for reviewers + + diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c3ee43c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,48 @@ +# Changelog + +All notable changes to Cyberfluids are documented here. The format is based on +[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to follow +[Semantic Versioning](https://semver.org/spec/v2.0.0.html) (pre-1.0: minor/patch may still +carry breaking changes while the API stabilizes). + +## [Unreleased] + +### Added +- **Installable package** — `install`/`export` rules and a generated `CyberfluidsConfig.cmake` + so downstream projects can `find_package(Cyberfluids)` and link `Cyberfluids::core` / + `Cyberfluids::c`. The C ABI shared library carries a semver `SOVERSION`. +- **Zero-setup dependency resolution** — NumPP is fetched at a pinned tag via FetchContent when + it is not already installed, so a plain `cmake -B build` works with no manual checkout + (`-DCYBERFLUIDS_FETCH_DEPS=OFF` to disable). +- **Benchmark reference** — `docs/benchmarks.md` records methodology and measured GLUPS across + CPU / CUDA / OpenCL; the `bench/wind_tunnel_bench.cpp` harness runs via `just bench`. +- **Project governance** — `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, this + changelog, and GitHub issue/PR templates. + +### Changed +- Documentation and OpenSpec specs brought back in sync with the shipped code (GPU backends + marked validated, dependency mechanism corrected, spec `Purpose` placeholders filled). + +## [0.0.1] - 2026-07-05 + +Initial tagged release — a zero-legacy C++20 Lattice Boltzmann CFD engine on the CyberdyneCorp +scientific suite (NumPP), single-node, no MPI. + +### Added +- **Physics** — BGK / TRT / MRT / regularized / forced dynamics; D2Q9, D2Q5, D3Q7, D3Q19, D3Q27 + stencils (2D and 3D); single- and multi-component Shan-Chen multiphase; Boussinesq thermal + (Rayleigh-Bénard); porous media (partial bounce-back); per-cell external forcing and + advection-diffusion coupling. +- **Geometry & wind tunnel** — STL/OBJ import + voxelization (CyberMeshGenerator); a 3D D3Q19 + wind tunnel with off-lattice bounce-back (analytic sphere or imported mesh). +- **Backends** — CPU (`std::execution::par_unseq` + serial fallback); validated CUDA and OpenCL + D3Q19 wind-tunnel device kernels (~30× the parallel CPU on an RTX 5060); Metal D2Q9 cavity. +- **Validation** — Palabos numerical oracle for the 2D and 3D lid-driven cavity; fp32 GPU + agreement with the fp64 CPU oracle to ~1e-5. +- **Bindings & I/O** — Python (NumPy / DLPack) and Swift bindings over a stable C ABI; + legacy-VTK structured-points output; checkpoint/restart. +- **Tooling** — a `justfile` (build, test, GPU, benchmark, spec), a GitHub Actions CI pipeline + (Linux GCC + macOS Metal/Swift + OpenSpec validation), and in-repo OpenSpec specs. + +[Unreleased]: https://github.com/CyberdyneCorp/Cyberfluids/compare/v0.0.1...HEAD +[0.0.1]: https://github.com/CyberdyneCorp/Cyberfluids/releases/tag/v0.0.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..23449bc --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,56 @@ +# 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, 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: + +- 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: + +- 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. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is +officially representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the +community leaders responsible for enforcement at **leonardoaraujo.santos@gmail.com**. All +complaints will be reviewed and investigated promptly and fairly. Community leaders are obligated +to respect the privacy and security of the reporter of any incident. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), +version 2.1, available at +. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..65602cb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,69 @@ +# Contributing to Cyberfluids + +Thanks for your interest in Cyberfluids — a zero-legacy C++20 Lattice Boltzmann CFD engine. +This guide covers how to build, the workflow we follow, and what a mergeable change looks like. + +## Getting set up + +```bash +git clone https://github.com/CyberdyneCorp/Cyberfluids.git +cd Cyberfluids +just bootstrap # build + install NumPP into .deps/ (or: scripts/bootstrap_deps.sh) +just test # configure + build + full CTest suite (CPU backend) +``` + +No `just`? The equivalent is `scripts/bootstrap_deps.sh` then `cmake -B build` + +`cmake --build build` + `ctest --test-dir build`. See +[docs/getting-started.md](docs/getting-started.md). GPU work: `just gpu-detect`, then +`just cuda` / `just opencl` / `just metal`. + +## Development workflow + +We develop spec-first with [OpenSpec](https://github.com/Fission-AI/OpenSpec). Living +capability specs are in [`openspec/specs/`](openspec/specs); completed changes are archived +under [`openspec/changes/archive/`](openspec/changes/archive). + +- **Medium or large features** (new physics, backends, bindings, build/packaging behavior): + start with an OpenSpec change (proposal → specs/tasks) before implementing. Run + `openspec validate --all --strict` — CI enforces it. +- **Small fixes and docs:** a direct PR is fine. Still keep the specs and docs truthful — if + your change makes a spec or doc statement false, update it in the same PR. + +## What a mergeable PR looks like + +- **Tests.** New behavior ships with tests. **Every bug fix includes a regression test** that + fails before the fix and passes after. +- **Green CI.** Linux (GCC, `par_unseq` + oracle suite), macOS (Metal build + Swift binding), + and OpenSpec validation must all pass. +- **Docs/specs in sync.** Update `docs/` and `openspec/specs/` when your change affects + documented behavior. Don't leave a claim that the code contradicts. +- **Readable, low-complexity code.** Match the surrounding style (Concepts, Ranges, smart + pointers, contiguous data — no raw owning pointers, no legacy macros). Keep per-function + cognitive complexity modest; isolate genuinely irreducible algorithms (kernels, AST-like + traversals) and flag them rather than mangling them to hit a number. +- **A descriptive PR message.** Explain what changed and why. If you found a bug, describe how + it reproduced. + +## Commit & PR style + +- Concise, technical, imperative commit subjects (e.g. "Fix Shan-Chen weight formula in docs"). +- Reference the OpenSpec change or issue when there is one. +- Keep unrelated changes in separate PRs. + +## Numerical correctness + +Physics changes are validated against **Palabos** as a numerical oracle (see +[docs/oracle-validation.md](docs/oracle-validation.md)) and GPU paths against the fp64 CPU +solver within a documented fp32 tolerance. If you change a collision model, boundary scheme, or +equilibrium, make sure the relevant oracle/GPU-vs-CPU tests still pass — and add one if a gap +exists. + +## Reporting bugs & requesting features + +Open an issue using the templates. For **security** issues, do **not** open a public issue — +see [SECURITY.md](SECURITY.md). + +## License + +By contributing, you agree that your contributions are licensed under the project's +[MIT License](LICENSE). diff --git a/README.md b/README.md index 3cfaa34..a5f342d 100644 --- a/README.md +++ b/README.md @@ -312,11 +312,19 @@ worldwide LBM community through Palabos. In tests, identical setups run in both their macroscopic fields are compared within a documented tolerance — see [oracle validation](docs/oracle-validation.md). +## 🧭 Versioning & API stability + +Cyberfluids is **pre-1.0 (`0.0.x`)**: the API is still settling, and minor/patch releases may +carry breaking changes until `1.0`. The C ABI shared library carries a semver `SOVERSION` +(`libcyberfluids_c.so.`) so consumers can pin ABI compatibility. Notable changes are +tracked in [CHANGELOG.md](CHANGELOG.md). + ## 🤝 Contributing Work is spec-driven. Before writing code, read the relevant spec in `openspec/specs/`, and open changes through the OpenSpec workflow (`/opsx:propose`). Every bug fix ships with a -regression test. +regression test. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full workflow, the +[Code of Conduct](CODE_OF_CONDUCT.md), and [security reporting](SECURITY.md). ## 📄 License diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..6e8fde9 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,37 @@ +# Security Policy + +Cyberfluids is a numerical simulation library. The most relevant risks are memory-safety issues +(out-of-bounds access, use-after-free) reachable through the C ABI or the geometry/STL import +path, and denial-of-service from untrusted input (e.g. a malformed mesh or an extreme grid size). + +## Supported versions + +The project is pre-1.0 (`0.0.x`). Security fixes are applied to `main` and released in the next +tag. There is no long-term-support branch yet. + +| Version | Supported | +|---------|-----------| +| `main` | ✅ | +| latest `0.0.x` tag | ✅ | +| older tags | ❌ | + +## Reporting a vulnerability + +**Please do not open a public issue for security vulnerabilities.** + +Report privately via GitHub's [**Report a vulnerability**](https://github.com/CyberdyneCorp/Cyberfluids/security/advisories/new) +(Security → Advisories), or email the maintainer at **leonardoaraujo.santos@gmail.com** with: + +- a description of the issue and its impact, +- steps or a minimal input that reproduces it (a mesh/config file, grid parameters, or a code + snippet driving the C ABI), +- affected version/commit. + +We aim to acknowledge a report within a few days and to agree on a disclosure timeline with you. +Please give us a reasonable window to ship a fix before any public disclosure. + +## Scope + +In scope: the core library, the C ABI, geometry import, and the language bindings in this repo. +Out of scope: vulnerabilities in third-party dependencies (report those upstream) and issues that +require running deliberately hostile build tooling. diff --git a/docs/roadmap.md b/docs/roadmap.md index d2e7e0e..c3c64e6 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -5,22 +5,24 @@ regressions where applicable). This is a plan, not a commitment of dates. ```mermaid flowchart LR - M0["M0 · Bootstrap MVP ✅"] --> M1["M1 · Dynamics & stencils"] - M1 --> M2["M2 · Geometry & I/O"] - M2 --> M3["M3 · GPU backends"] - M3 --> M4["M4 · Multiphysics"] + M0["M0 · Bootstrap MVP ✅"] --> M1["M1 · Dynamics & stencils ✅"] + M1 --> M2["M2 · Geometry & I/O ✅"] + M2 --> M3["M3 · GPU backends 🟡"] + M3 --> M4["M4 · Multiphysics ✅"] M4 --> M5["M5 · Mobile & bindings GA"] ``` -## M0 — Bootstrap MVP *(done — 12/12 tests, Palabos-validated)* +Milestones **M0–M2 and M4 are complete**; **M3** is done except SYCL; **M5** (mobile + bindings +GA) is the active frontier, alongside packaging and analysis features called out below. -[`bootstrap-cyberfluids-core`](../openspec/changes/bootstrap-cyberfluids-core): CMake + -NumPP, D2Q9+D3Q19, BGK, collide-and-stream, bounce-back + moving-wall + Zou/He + periodic, -CPU backend, 2D+3D lid-driven cavity, Palabos oracle regression (~0.8% RMS of U), Python + -Swift bindings. Deferred within M0: generic multi-face velocity BC, iOS/Android toolchains, -and a 3D oracle reference. +## M0 — Bootstrap MVP *(done — Palabos-validated)* -## M1 — Dynamics & stencils +[`bootstrap-cyberfluids-core`](../openspec/changes/archive/2026-07-04-bootstrap-cyberfluids-core): +CMake + NumPP, D2Q9+D3Q19, BGK, collide-and-stream, bounce-back + moving-wall + Zou/He + +periodic, CPU backend, 2D+3D lid-driven cavity, Palabos oracle regression (~0.8% RMS of U), +Python + Swift bindings. + +## M1 — Dynamics & stencils *(done)* TRT, MRT, regularized, and forced dynamics; D3Q27 and D2Q5/D3Q7 advection-diffusion descriptors. @@ -35,20 +37,30 @@ so imported geometry becomes walls with no new collision/streaming code. Validated by voxel-volume convergence, geometry-defined Poiseuille flow, and a CyberMeshGenerator STL round-trip. -## M3 — GPU backends +## M3 — GPU backends *(mostly done)* -Metal (Apple Silicon) and CUDA (NVIDIA), then OpenCL/SYCL — each behind the backend seam, -validated against the CPU path. +Metal (Apple Silicon, D2Q9 cavity), CUDA (NVIDIA), and OpenCL — each behind the backend seam and +validated against the CPU path. CUDA/OpenCL reach ~30× the parallel CPU on an RTX 5060 (see +[benchmarks](benchmarks.md)). **Remaining:** SYCL (AMD/Intel/integrated), and GPU coverage in CI +(currently validated on developer hardware only). -## M4 — Multiphysics +## M4 — Multiphysics *(done)* Shan-Chen multi-component/multiphase, porous media (partial bounce-back), thermal flow (Boussinesq + advection-diffusion coupling). -## M5 — Mobile & bindings GA +## M5 — Mobile & bindings GA *(active)* + +iOS/iPadOS and Android NDK toolchain builds, hardened and exercised in CI; Python and Swift +bindings to general availability with full field interop — including a self-contained, +`pip install`-able Python wheel that builds the C ABI (the install/export groundwork is in place). + +## Beyond the milestones -iOS/iPadOS and Android NDK builds hardened; Python and Swift bindings to general -availability with full field interop. +- **Analysis:** momentum-exchange **drag/lift** reporting for the wind tunnel (force coefficients). +- **Packaging:** Conan/vcpkg packages for Cyberfluids and NumPP (an installable + `find_package(Cyberfluids)` already ships; see [getting-started](getting-started.md)). +- **Physics depth:** turbulence models (LES/Smagorinsky) and additional boundary schemes. See open capabilities in [features](features.md) and the target contract in [`../openspec/specs/`](../openspec/specs).