From f9b20ac9494df799e3fe833f84b11198a189c379 Mon Sep 17 00:00:00 2001 From: HugoFara Date: Wed, 12 Aug 2026 23:20:26 +0200 Subject: [PATCH 1/2] docs: add a CHANGELOG The repository has seven tags and six GitHub releases, and no file that tells a user what changed between them. `pip install forefire` makes that worse: someone pinning a version has the release notes on GitHub and nothing in the tree. CHANGELOG.md reconstructs every release from the release notes and the commit history. Claims that could be checked were checked against the tags: listenHTTP and RothermelAndrews2018 are absent at v1.2 and present at v2.0, the geojson dump mode is absent at v1.1.10. [Unreleased] lists only what is on this branch, #154 and #155. The dev branch carries a longer list in its own copy, which supersedes this one when dev is merged. CONTRIBUTING.md now asks for an entry, so the file stays current instead of being reconstructed again in a year. Its link to a testing page pointed at a Read the Docs URL that has never existed; it points at TESTING.md, which nothing in the repository linked to. (cherry picked from commit cc7e1789c66432aec56673993c3b6e198e0525a0) --- CHANGELOG.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 11 ++-- README.md | 2 + 3 files changed, 146 insertions(+), 4 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..a5644e65 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,137 @@ +# Changelog + +All notable changes to ForeFire are recorded here. + +The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +Version numbers are the tags in this repository and the values reported by +`forefire -v`; they are also what `pip install forefire==` resolves. + +Entries below v2.5.0 were reconstructed from the release notes and the commit +history, so they summarise each release rather than list every change. The +`Full Changelog` link on each version gives the complete commit range. + +## [Unreleased] + +Merged since v2.5.0. Work still on the `dev` branch is listed in that branch's +copy of this file. + +### Changed + +- Linux wheels are built against a NetCDF without DAP and HDF4, roughly halving + the wheel. ([#154]) +- Free-threaded (`cp314t`) wheels are no longer published, because the core is + not yet thread-safe; CPython 3.14 is declared supported. ([#155]) + +## [v2.5.0] — 2026-08-11 + +### Added + +- **Pip-installable wheels** for Linux (x86_64, aarch64) and macOS (Apple + Silicon and Intel), CPython 3.9 and newer. `pip install forefire` gives both + the `forefire` command-line interpreter and the `pyforefire` module, with + NetCDF bundled inside the wheel. Wheels are built without MPI and without + `-march=native`. ([#151]) + +### Changed + +- The Dockerfile is a multi-stage build, and only `libforefireL` is built in + the builder stage. ([#147]) +- The `install-forefire.sh` build is driven by an option-based `CMakeLists.txt` + (`FOREFIRE_ENABLE_MPI`, `FOREFIRE_NATIVE_ARCH`, `FOREFIRE_BUILD_PYTHON`, + `FOREFIRE_STATIC_CORE`, `FOREFIRE_BUILD_TOOLS`, `FOREFIRE_CHECK_LFS`). + +### Fixed + +- A double free in `FireFront` cleanup. ([#145]) +- `CMakeLists.txt` was matched by `.gitignore`, so it was missing from the + source distribution. ([#152]) +- Bugs in `tests/run.bash`, including a `runANN` typo and an unreachable + `./clean.bash`. ([#146]) + +**Full Changelog**: + +## [v2.4.2] — 2025-11-27 + +- Simplified the installation process, following review comments on the JOSS + submission, and corrected the installation instructions. +- Aligned the coupling with + [PACK-MNH-V5-7-2](https://src.koda.cnrs.fr/mesonh/mesonh-code/-/releases/PACK-MNH-V5-7-2). +- Aligned the repository with the accepted JOSS paper + ([10.21105/joss.08680](https://doi.org/10.21105/joss.08680)). + +**Full Changelog**: + +## [v2.1.122] — 2025-09-16 + +Tagged, but never published as a GitHub release. + +- Docker images published to the GitHub container registry, and tested in CI. +- Python bindings reworked, with the example from [#103] applied. +- macOS CI runs the test script. + +**Full Changelog**: + +## [v2.0] — 2025-06-05 + +The V2 release: the HTTP interface, and alignment with Meso-NH V4.7.2. + +### Added + +- The built-in **HTTP command server and web UI** (`listenHTTP[]`, or + `forefire -l`), serving a map view of the simulation. +- The **Read the Docs documentation site**, built with Sphinx, Breathe and + Doxygen. +- `install-forefire.sh`, with `-y` to add `forefire` to `PATH` and set + `FOREFIREHOME`. +- A working Dockerfile, and GitHub Actions for Linux and macOS. +- The `RothermelAndrews2018` propagation model. ([#34]) + +### Changed + +- CMake replaces SCons throughout; references to SCons were removed. + +### Fixed + +- The `-lnetcdf_c++4` link failure. ([#26]) +- A division by zero in `setArrivalTime`/`getArrivalTime`. ([#36]) + +**Full Changelog**: + +## [v1.2] — 2024-01-16 + +### Added + +- The `geojson` dump mode. + +## [v1.1.10] — 2022-10-25 + +### Changed + +- CMake became the default build system. ([#9]) + +## [v1.1.0] — 2022-09-28 + +Tagged before the sources were moved into `src/`, so that this point in the +repository stays easy to return to. + +[Unreleased]: https://github.com/forefireAPI/forefire/compare/v2.5.0...dev +[v2.5.0]: https://github.com/forefireAPI/forefire/releases/tag/v2.5.0 +[v2.4.2]: https://github.com/forefireAPI/forefire/releases/tag/v2.4.2 +[v2.1.122]: https://github.com/forefireAPI/forefire/releases/tag/v2.1.122 +[v2.0]: https://github.com/forefireAPI/forefire/releases/tag/v2.0 +[v1.2]: https://github.com/forefireAPI/forefire/releases/tag/v1.2 +[v1.1.10]: https://github.com/forefireAPI/forefire/releases/tag/v1.1.10 +[v1.1.0]: https://github.com/forefireAPI/forefire/releases/tag/v1.1.0 + +[#9]: https://github.com/forefireAPI/forefire/issues/9 +[#26]: https://github.com/forefireAPI/forefire/pull/26 +[#34]: https://github.com/forefireAPI/forefire/pull/34 +[#36]: https://github.com/forefireAPI/forefire/pull/36 +[#103]: https://github.com/forefireAPI/forefire/issues/103 +[#145]: https://github.com/forefireAPI/forefire/pull/145 +[#146]: https://github.com/forefireAPI/forefire/pull/146 +[#147]: https://github.com/forefireAPI/forefire/pull/147 +[#151]: https://github.com/forefireAPI/forefire/pull/151 +[#152]: https://github.com/forefireAPI/forefire/pull/152 +[#154]: https://github.com/forefireAPI/forefire/pull/154 +[#155]: https://github.com/forefireAPI/forefire/pull/155 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3becf3bc..0c8a0305 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,25 +64,28 @@ We welcome code contributions, from bug fixes to new features. Implement your code changes, following existing coding style and conventions where possible. 6. **Add Tests (if applicable):** - For new features or significant bug fixes, please add corresponding tests or update existing ones. See the [Testing Documentation](https://forefire.readthedocs.io/en/latest/developer_guide/testing.html) *(Placeholder: Link to testing section once created)* for details on how to run tests. Ensure all tests pass locally. + For new features or significant bug fixes, please add corresponding tests or update existing ones. See [TESTING.md](TESTING.md) for what each suite covers and how to run it. Ensure all tests pass locally. ```bash # Example command to run tests (adjust as needed) cd tests && bash run.bash ``` -7. **Commit Changes:** +7. **Record the Change:** + + Add an entry under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md), in the section that fits (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`). Write it for someone upgrading: what changed for them, not what you edited. Skip this for changes with no user-visible effect, such as a typo fix or an internal refactor. +8. **Commit Changes:** Commit your changes with clear and concise commit messages. ```bash git add . git commit -m "feat: Implement new flux model calculation" ``` -8. **Push to Your Fork:** +9. **Push to Your Fork:** Push your branch to your GitHub fork. ```bash git push origin my-feature-branch ``` -9. **Open a Pull Request (PR):** +10. **Open a Pull Request (PR):** Go to the `forefireAPI/forefire` repository on GitHub and open a Pull Request from your branch to the `dev` branch (or `master` if that's the target). * Provide a clear description of the changes in the PR. diff --git a/README.md b/README.md index 229a53e3..0e492164 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,8 @@ - 📚 **Full Documentation:** [forefire.readthedocs.io](https://forefire.readthedocs.io/en/latest/) - 🚀 **Live Demo:** [forefire.univ-corse.fr/sim](http://forefire.univ-corse.fr/sim) - 🌍 **Website:** [forefire.univ-corse.fr](https://forefire.univ-corse.fr/) +- 📝 **Changelog:** [CHANGELOG.md](CHANGELOG.md) — what each release changed +- 🧪 **Testing:** [TESTING.md](TESTING.md) — how to run each test suite ## Features From b8c562f2f2cd8737c7eec6d031048095ffb58de4 Mon Sep 17 00:00:00 2001 From: HugoFara Date: Wed, 12 Aug 2026 23:21:24 +0200 Subject: [PATCH 2/2] docs: record the dev-only work, and the options it added The CHANGELOG landed on master carries only #154 and #155 under [Unreleased], because that is all master has. This adds the ten pull requests merged into dev since: the unit suite, the moisture invariants, the sanitizer job, the HTTP characterisation tests, the threading reproduction, and the shared-state and double-free fixes. Two things went stale on dev while that work landed, both of them ours. The README's CMake option table stopped at six options; #156 and #180 added FOREFIRE_BUILD_TESTS, FOREFIRE_ENABLE_WARNINGS, FOREFIRE_WARNINGS_AS_ERRORS and FOREFIRE_SANITIZE. And CONTRIBUTING told contributors to run `cd tests && bash run.bash`, which does not reach the C++ unit tests at all; ctest does. --- CHANGELOG.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++-- CONTRIBUTING.md | 8 +++++-- README.md | 8 ++++++- 3 files changed, 69 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a5644e65..6d77f867 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,8 +12,52 @@ history, so they summarise each release rather than list every change. The ## [Unreleased] -Merged since v2.5.0. Work still on the `dev` branch is listed in that branch's -copy of this file. +Merged since v2.5.0, not yet released. + +### Added + +- C++ unit tests covering every propagation and flux model, built by default + and registered with CTest. They exercise the models one call at a time, + which the `runff` regression test cannot reach. ([#156]) +- A dead fuel moisture invariant suite (`tests/python/test_moisture_invariants.py`) + and the `invariants.yml` workflow that runs it. Unlike `runff` it holds no + reference data: every assertion follows from the published spread equations, + so it stays valid across recalibration. ([#158]) +- A blocking AddressSanitizer job, and `-DFOREFIRE_SANITIZE=` to build + with `-fsanitize=` on the compile line, the executables and the shared + library. ([#180]) +- Characterisation tests pinning the HTTP command server's current behaviour. + ([#174]) +- A concurrency stress test for free-threaded CPython + (`tests/python/test_threading.py`). It does not pass yet: it is the failing + test for the shared-state work in [#175]. ([#176]) +- `-Wall -Wextra` on ForeFire's own sources, with `FOREFIRE_ENABLE_WARNINGS` + and `FOREFIRE_WARNINGS_AS_ERRORS` to control them. NetCDF's headers are + included as system headers so their warnings do not appear. ([#156]) +- `FOREFIRE_BUILD_TESTS` (default on outside wheel builds) to build the unit + tests. ([#156]) +- `TESTING.md` now documents every suite, how to run it, and which ones CI + validates. + +### Fixed + +- Rate of spread stayed finite and decreasing at high dead fuel moisture, and + `DataBroker` no longer serves `moisture` through the five-slot getter, which + returned a neighbouring property. ([#158]) +- The model properties array was freed twice on destruction. ([#157]) +- `~ForeFireModel` freed an uninitialised pointer when construction had not + reached the allocation. ([#156]) +- `runANN` had failed on its second line since it was committed: it diffed + against `result.txt.ref`, a file that is not in the repository. It now checks + the root mean squared error that `ANN_test` already computes, which does not + depend on the last digit of a machine-specific reference, and it runs in CI. + ([#183]) +- The `ForeFireAtom` instance counter is now atomic and the `SimulationParameters` + singleton is initialised safely, so two threads no longer race for ids or + construct the singleton twice. ([#177]) +- `StringRepresentation` kept its output buffer, current level and GeoJSON + cursor in file-scope globals shared by every instance. They are now members. + ([#178]) ### Changed @@ -135,3 +179,13 @@ repository stays easy to return to. [#152]: https://github.com/forefireAPI/forefire/pull/152 [#154]: https://github.com/forefireAPI/forefire/pull/154 [#155]: https://github.com/forefireAPI/forefire/pull/155 +[#156]: https://github.com/forefireAPI/forefire/pull/156 +[#157]: https://github.com/forefireAPI/forefire/pull/157 +[#158]: https://github.com/forefireAPI/forefire/pull/158 +[#174]: https://github.com/forefireAPI/forefire/pull/174 +[#175]: https://github.com/forefireAPI/forefire/issues/175 +[#176]: https://github.com/forefireAPI/forefire/pull/176 +[#177]: https://github.com/forefireAPI/forefire/pull/177 +[#178]: https://github.com/forefireAPI/forefire/pull/178 +[#180]: https://github.com/forefireAPI/forefire/pull/180 +[#183]: https://github.com/forefireAPI/forefire/pull/183 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c8a0305..48a18128 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,9 +64,13 @@ We welcome code contributions, from bug fixes to new features. Implement your code changes, following existing coding style and conventions where possible. 6. **Add Tests (if applicable):** - For new features or significant bug fixes, please add corresponding tests or update existing ones. See [TESTING.md](TESTING.md) for what each suite covers and how to run it. Ensure all tests pass locally. + For new features or significant bug fixes, please add corresponding tests or update existing ones. See [TESTING.md](TESTING.md) for what each suite covers, how to run it, and which ones CI validates. Ensure all tests pass locally. ```bash - # Example command to run tests (adjust as needed) + # The C++ unit tests + cmake -S . -B build && cmake --build build -j + ctest --test-dir build --output-on-failure + + # The script-driven suites (runff, runANN) cd tests && bash run.bash ``` 7. **Record the Change:** diff --git a/README.md b/README.md index 0e492164..b70952c1 100644 --- a/README.md +++ b/README.md @@ -159,9 +159,15 @@ The CMake build is option-driven. The defaults below are what a plain | `FOREFIRE_STATIC_CORE` | `OFF` | Build the core as a static library instead of `libforefireL`. | | `FOREFIRE_BUILD_TOOLS` | `ON` | Build the `ANN_test` helper executable. | | `FOREFIRE_CHECK_LFS` | `ON` | Run the Git LFS integrity check while configuring. | +| `FOREFIRE_BUILD_TESTS` | `ON` | Build the C++ unit tests and register them with CTest. | +| `FOREFIRE_ENABLE_WARNINGS` | `ON` | Compile ForeFire's own sources with `-Wall -Wextra`. | +| `FOREFIRE_WARNINGS_AS_ERRORS` | `OFF` | Fail the build on any compiler warning. Not yet usable repository-wide. | +| `FOREFIRE_SANITIZE` | `""` | Sanitizers to build with, passed to `-fsanitize=` (e.g. `address`). | Wheel builds (anything driven by `pip`) flip these to the portable defaults: -no MPI, no `-march=native`, static core, Python module on. +no MPI, no `-march=native`, static core, Python module on, no tools, no tests. + +`TESTING.md` covers the test suites and the sanitizer build in detail. ## Python Bindings ForeFire provides Python bindings for easier scripting and integration: