Developer Guidelines​#

This page is for contributors working on PlantSimEngine itself. It focuses on the local development workflow, the checks worth running before opening a pull request, and a few implementation details that are easy to miss.

Working on PlantSimEngine​#

Clone the repository from GitHub and develop against a checked-out local copy, typically through Pkg.develop(path="...").

We mostly follow the Julia manual's style guide. Questions, bug reports, and design discussions should go through GitHub issues or the related pull request.

The Roadmap summarizes longer-term work that is not yet complete.

Local environments​#

PlantSimEngine currently has three main local environments:

• test/ for the package test suite and doctests run from test/runtests.jl;

• docs/ for the Documenter build;

• benchmark/ for benchmark scripts used to compare performance locally.

Running checks locally​#

Main test suite​#

Run the standard test suite from the repository root:

julia --project=test test/runtests.jl

The current public runtime is sequential. Running with multiple Julia threads does not enable a parallel Composite model executor; parallel execution remains roadmap work and requires dedicated correctness tests before it becomes public.

Documentation​#

The website uses Documenter and Bonito's static documentation writer. The docs environment requires Julia 1.11 or newer; this does not change the Julia versions supported by PlantSimEngine itself.

Start Julia from docs/ with that directory as the active project (agents use Kaimon), then install the docs dependencies and build without deploying:

using Pkg
Pkg.instantiate()
ENV["PLANTSIMENGINE_DOCS_BUILD_ONLY"] = "true"
include("make.jl")

The docs environment resolves PlantSimEngine from the parent checkout and includes the packages needed for the runnable examples and API reference. Build output is written to docs/build/. The build also checks that exported pages, assets, and Bonito session data resolve locally. docs/check_static_export.jl adjusts Bonito 5.2's site-relative links for this manual's nested pages and for version links in pull-request previews; its assertions flag upstream changes that need review. docs/bonito_rendering.jl preserves code blocks and tables returned by @eval; it defers to Bonito if a later version supplies the missing document-root renderer.

Serve the build directory over HTTP to inspect the theme, search, and static examples:

using LiveServer
LiveServer.serve(dir="build", launch_browser=true)

The existing documentation job builds and deploys the static files through Documenter, including pull-request previews. The website needs no running Julia server. Browser interactions can inspect exported data; rerunning a Julia model requires an execution backend.

Benchmarks​#

Benchmark scripts live in benchmark/. They are useful when a change may alter runtime characteristics, but they are not a substitute for the main test suite or downstream integration checks.

For phase-oriented diagnostics, opt in explicitly:

simulation = run!(model; steps=48, outputs=:none, performance=true)
Diagnostics.explain_runtime_performance(simulation)

The report separates time spent preparing the simulation, selecting objects, updating after structural changes, running the models, and collecting outputs. Use it to find which stage takes time. Measuring those stages also adds some work, so measure normal execution separately with performance=false after a first run has allowed Julia to compile the code.

CI workflows​#

The repository currently relies on these GitHub Actions workflows:

• CI.yml for the main test matrix, docs build, and coverage;

• Integration.yml for downstream checks against packages that depend on PlantSimEngine;

• Benchmarks.yml for pull-request benchmark runs;

• register.yml and TagBot.yml for release automation.

If a change affects public APIs or execution behavior, check both CI and Integration before merging. Benchmark results are useful for regressions, but should be interpreted alongside the test results.

Downstream tests run the test suites of packages that use PlantSimEngine, such as PlantBiophysics, against the proposed changes. If you maintain a package that depends on PlantSimEngine, you can propose adding it to the integration workflow through a pull request.

Graph Viewer Frontend​#

The static viewer and HTTP editor share the React application under frontend/. PlantSimEngine releases include the production bundle in frontend/dist, because Julia package installations do not run Node or Vite. The content hash in asset filenames is intentional: it prevents browsers and documentation hosts from reusing stale JavaScript after a release.

Install the frontend development dependencies from the repository root:

cd frontend
npm ci

Run the fast checks while developing:

npm run typecheck
npm test

Build the production assets after changing TypeScript, CSS, or frontend dependencies:

npm run build

Commit the resulting frontend/dist changes together with the source changes. Do not commit frontend/node_modules, Playwright reports, screenshots, videos, or local test output.

The end-to-end suite starts a real Julia GraphEditor.edit_graph session and controls it with Chromium:

npx playwright install chromium
npm run test:e2e

Use npm run test:e2e:ui for a headed local debugging session. The tests use stable data-testid attributes for commands and confirm mutations through the Julia /state endpoint. Avoid assertions against generated CSS classes or implementing PlantSimEngine selector semantics in TypeScript.

Core graph DTO and edit tests live in test/test-model-graph-view.jl. HTTP-extension tests live in test/test-model-graph-editor-extension.jl. When changing the graph schema, update those Julia tests, frontend types, unit tests, Playwright scenarios, and the committed production bundle in the same change.

Documentation impact​#

The manual has two practical paths: Couple models for simulation users and Write models for model authors. Add an example to the appropriate path and link to deeper reference material only when the reader needs it. Prefer one tested example that develops gradually over several parallel quickstarts.

Describe current behavior in the user guides and API reference. Completed work plans and handoff notes do not belong in the manual; keep lasting explanations with the feature they describe.

Documentation fixes are welcome through GitHub issues or a pull request. A short report of a confusing example is useful even without a proposed fix.

Changes in PlantSimEngine often require documentation updates beyond the page you were editing.

• User-facing errors often require updates to the troubleshooting pages.

• New examples should ideally become doctests or rendered examples.

• API or behavior changes may require updates to the roadmap, migration notes, and example pages.

• If a feature remains experimental, say so clearly in the docs instead of letting examples imply stable support.

Pull request checklist​#

• Make sure the change is covered by tests.

• Run the main test suite locally.

• Build the documentation locally if docstrings, examples, or APIs changed.

• Review the affected docs pages and update them in the same pull request.

• Check GitHub Actions after pushing.

• If the change is breaking or deprecates an old path, document the migration path before merging.

Implementation notes​#

Coverage gaps to keep in mind​#

PlantSimEngine's own tests cannot cover every weather format, object configuration, and use in other packages. When changing public functions or how simulations run, also run the tests of packages that depend on them.