diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc60a76..3936ad1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,7 +1,21 @@ # Contributing to Ashvale Station -Thanks for taking an interest. This is a small project maintained by one person, -so the bar here is "make it easy to say yes", not "follow a 40-page process". +Read this first, so nobody wastes an afternoon. + +**This is a solo project.** It is written and maintained by one person, for one +weather station, and it is published because the methods may be useful to +someone else, not because it is looking for a team. + +**Bug reports are genuinely welcome.** If something crashes, forecasts badly, or +the documentation is wrong, open an issue. That is useful and I will read it. + +**Pull requests are unlikely to be merged.** Not from lack of gratitude: this +codebase carries a lot of hard-won reasoning in its comments and docstrings, and +reviewing changes to it properly costs more time than I have. If you want it to +do something different, fork it. Apache 2.0 exists precisely so you can. + +The rest of this file documents how the project holds itself to a standard. It +is written for anyone reading the code, including future me. ## Ground rules that actually matter @@ -54,7 +68,10 @@ python run.py --no-led # dashboard on :8000 No Sense HAT needed. The simulator kicks in automatically and exercises every code path. -## Before you open a pull request +## The bar any change has to clear + +Whether it is my own commit or a fork of yours, a change to the forecasting +path is not finished until it can show: - [ ] `python scripts/evaluate.py` runs clean, and you have posted before/after numbers - [ ] Those numbers came from a backfill with `--seed` and `--end` both pinned @@ -63,16 +80,18 @@ code path. - [ ] New model code explains its failure mode in the docstring - [ ] The dashboard still fits one viewport at 1280x800 if you changed the UI -## Good first contributions +## Roadmap + +Where this is going, in rough order of value. Listed so a forker knows what is +already planned rather than as an invitation. - **DS18B20 or BME280 support.** An outdoor sensor removes the single biggest limitation in the project. High impact, self-contained. - **Tipping-bucket rain gauge on GPIO.** Real precipitation labels would transform the precipitation model. - **METAR ingestion** from a nearby airfield as a calibration reference. -- **Translations** for the dashboard. - **Tests.** There is a walk-forward backtest but no unit test suite. A pytest - suite over `physics.py`, `estimation.py` and `models/rls.py` would be very welcome. + suite over `physics.py`, `estimation.py` and `models/rls.py` is the main gap. ## Reporting bugs @@ -81,8 +100,8 @@ output of `GET /api/status`, and what you expected instead. If it is a forecasting problem rather than a crash, the output of `scripts/evaluate.py` helps enormously. -## Licensing of contributions +## Licensing -By contributing you agree that your work is licensed under the Apache License -2.0, the same terms as the project. You keep the copyright in your own -contributions. +The project is Apache 2.0. Fork it, modify it, ship it, subject to the licence +terms. In the unlikely event a patch is accepted, it is taken under the same +terms and you keep the copyright in your own work. diff --git a/README.md b/README.md index c00c4d8..1270f54 100644 --- a/README.md +++ b/README.md @@ -160,18 +160,21 @@ permanently. ## The dashboard -Five tabs, one viewport, no scrolling on desktop. Below 1024 px the constraint is -released, because pinning five panels into a phone viewport produces unreadable +Four tabs, one viewport, no scrolling on desktop. Below 1024 px the constraint is +released, because pinning four panels into a phone viewport produces unreadable eight-pixel type. | Tab | Answers | | --- | --- | -| **Live** | What is it doing right now | -| **Forecast** | What is it about to do, and how sure are we | +| **Live** | What is it doing now, what it expects next, and how sure it is | | **History** | What did it do, over any timeframe you ask for | | **Models** | Has the model earned its confidence | | **Methods** | How the whole thing is wired, and how each stage fails | +Live carries the current readings, the observed-and-forecast chart with its 90% +conformal band, and the precipitation panel together, so the question "what is +it doing and what happens next" is answered without changing tab. + ### History Presets from 6 hours to a year, plus an explicit from/to range picker. Aggregation diff --git a/ashvale/dashboard.py b/ashvale/dashboard.py index 12dbe4b..f81b2ab 100644 --- a/ashvale/dashboard.py +++ b/ashvale/dashboard.py @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -"""The dashboard: five tabs, one viewport, no scrolling. +"""The dashboard: four tabs, one viewport, no scrolling. Layout contract. The page is a fixed three-row grid pinned to the viewport height: header, tab bar, then a content region that takes the @@ -119,7 +119,6 @@ DASHBOARD_HTML = r"""