Changelog
All notable changes to this project are recorded here. The format follows Keep a Changelog; versions follow Semantic Versioning.
Unreleased
Breaking changes
Old names keep working until 0.7.0, with a warning. See the migration page, docs/source/migrating_0_6_0.rst (“Upgrading from 0.5 to 0.6” in the documentation), for every renamed name.
YAML keys name their unit:
duration_minutes,delay_start_minutes,buffer_time_minutes,turnaround_time_minutes,water_depth_m,operation_depth_m,vessel_speed_kt,default_vessel_speed_kt,distance_between_stations_km,default_distance_between_stations_km,ctd_descent_rate_m_s,ctd_ascent_rate_m_s. The old keys are read with one warning per key per file until 0.7.0;enrichwrites the new keys.delay_endis removed: it was never read. It is ignored with a warning namingdelay_start_minutes,buffer_time_minutesandduration_minutes.Timelines are lists of frozen
ActivityRecordobjects (cruiseplan.Timeline), not dictionaries; reading a record like a dictionary warns until 0.7.0.CruiseScheduleis a deprecated alias ofTimeline. Records havekind,planned_duration_minutes, andwater_depth_m,operation_depth_m,delay_start_minutes(renamed).NetCDF schedule:
durationin minutes (was hours, now the actual duration) plusplanned_duration;dist_nmrenameddistance; times CF-encoded UTC seconds; every numeric variable has a UDUNITS-2units. Files written by 0.5.0 still read inlistandforecastuntil 0.7.0.Unknown YAML keys warn (one warning per key per file); they are rejected in the release after 0.6.0. An activity listed twice in a leg warns (it is still scheduled twice).
forecastanchored on a transit row starts that transit at--start-time(it started the operation after it).
Fixed
A leg’s
turnaround_time_minuteswas read but CTD casts always used the cruise value; the leg value now applies to its casts.The schedule total (CLI, HTML, result summary) left out waiting from positive
delay_start_minutes; it is the elapsed time.CSV times were truncated to the minute; they are rounded to the nearest minute (TeX plans keep 10 minutes).
Line records reported the cruise speed instead of the line’s own speed.
An operation’s positive
delay_start_minutesis waiting before it: a row “Waiting before” (kind wait) at the operation’s position, so no other record gets longer. A negative one means the operation started earlier: it comes out of the transit into it, then out of the operation before that transit, never below 0 min, and always warns that it is a quick fix (transit_minutesorduration_minuteson the record that was shorter says what happened). When the leg start is reached, the leg is not moved and the warning says how to start the leg earlier (the cruisestart_date/start_timefor the first leg; otherwise the leg’sdelay_start_minutesor the end of the previous leg). Records neither overlap nor leave gaps (duration_minutesactual,planned_duration_minutesplanned), the durations add up to the elapsed time apart from leg delays, and the forecast uses the same records. Schedules written before 0.6.0 keep their rows: a positive delay stays a gap, a negative one shortens the transit before the operation.Enriched values (
bathymetry_source, decimal-minute strings,bathymetry_provenance) are declared model fields; enrich no longer writes through__dict__.forecast --current-positionchanged only the waypoints header line. It now adds a transit from that position to the anchored operation at the leg speed, so the times change in every format (text, tex, waypoints, kml, png); the ship position itself is marked in the text and waypoints outputs only.forecast --current-position -74.62,164.30(negative first coordinate after a space) was rejected as an unknown option; that form,lat lonas two values of any sign (65.0 -30.0,65.0 30.0) and the=form all parse.TeX plan: a time rounded past midnight (23:56 → 00:00) is printed under the next day.
Waypoints without
--start-timeat 23:55 or later started at 00:00 of the same day; the rounding carries into the date.Forecast rows overlapped where an operation has a negative
delay_start; the transit before the operation is now shorter instead, as in the schedule.KML forecast had no placemarks (records lacked the fields the KML writer reads).
A forecast window with no operation in it (only a transit) wrote an empty plan; every format now stops with an error naming the window.
--current-positionwithin 0.05 nm of the anchored operation inserted a zero-length transit; it is skipped.Times in the TeX, waypoints, KML and CSV outputs are rounded on the full time, halves up (12:05 → 12:10 in the 10-minute TeX tables; 12:00:30 → 12:01 elsewhere). Before, seconds were dropped and Python’s half-to-even rounding was used, so regenerated tables of an unchanged schedule can differ by one step. The TeX time column is labelled UTC.
forecast --format texprints ship time when--start-timecarries the ship’s zone (2026-08-30T14:00+03:00): the rows are in that local time and the time column readsLT (UTC+03:00). Without a zone the table is in UTC and says so (it saidLTwhatever the times were).forecast --start-timeis UTC: a time with a zone is converted, a time without one is taken as UTC; waypoints without--start-timestart from the current UTC time. Forecast times are whole seconds (no “Discarding nonzero nanoseconds” warning).NetCDF schedule stores
delay_start(minutes) so it round-trips; files without it still read.Missing, partial or unreadable bathymetry file: depth lookups return the fill value
-9999.0(DEFAULT_DEPTH) with a WARNING naming the file and thecruiseplan bathymetrycommand, instead of formula (“mock”) depths. Maps are drawn without bathymetry. Mock mode removed.A requested bathymetry source is never silently switched for another dataset. When its file is missing the WARNING names the other sources present in the directory and the
--bathy-sourcevalue to use one of them.A station over land (bathymetry elevation
>= 0) was stored as a positive depth viaabs(elevation); it now gets the fill value-9999.0and a WARNING. Ocean depth is-elevation.Bathymetry grids stored north-to-south (descending latitude) returned the fill value for every point; the coordinate axes are flipped to ascending on load and indices are mapped back to the file on read.
A fill-value depth printed as
-9999 m/-9999in the LaTeX letsgo table and the HTML mooring table; both now showfill, as the other tables already did.get_depthreturned a fill-valueoperation_depthin preference to a validwater_depth, and a mooring carrying anoperation_depthwas timed as a CTD cast; the fill value is skipped and moorings take the mooring-duration path.cruiseplan bathymetry --bathy-source gebco2023downloaded ETOPO 2022.gebco2023is no longer a download choice (no download location);download_bathymetryraisesValueErrorfor it and for unknown sources. It stays a lookup source for a hand-placedGEBCO_2023.nc.Enriched YAML dropped
start_date,start_time,default_vessel_speed,default_distance_between_stations, CTD rates and day hours, sorunscheduled from defaults (e.g. a 1970 start). It also wrote the ports catalog underport:.Mooring or yo-yo cast without
durationgot 60 min inschedule(from a config field that does not exist) and 999 h inenrich. A CTD without a usable depth and an operation type without a duration rule got 0 min. All now get the 999 h fill (DEFAULT_MOORING_DURATION_MIN), with one WARNING per operation.Degrees-decimal-minutes output did not carry (
59°60.00'). Oneutils.coordinates.ddm_partswith carry is used by LaTeX, HTML, CSV, bridge waypoints, forecast text, YAML decmin fields and the station picker.LaTeX letsgo table chose the depth column by label text (
ctd,fd-,ds-, …); it now uses the record kind.HTML report put activities with an unknown leg into the first leg; they are listed under an “Unassigned” heading with a WARNING.
Leg.get_operational_entry_point/get_operational_exit_pointimported a removed module; they resolve throughOperationFactory.Depth validation treated
-9999from the bathymetry as a 9999 m depth; the fill value is reported as unverifiable.Missing-bathymetry messages referred to a
cruiseplan downloadcommand that does not exist.data/pycnmix-2026-v1.yamlreferenced seven activities by site name; they now name the_recovery/_deploymentpoints.
Added
cruiseplan.Timeline,cruiseplan.ActivityRecord(cruiseplan.timeline.record): one frozen record type withkind, used by every writer and the forecast.cruiseplan._deprecated: one table each of renamed YAML keys, removed keys, record keys and API names, with the removal release;cruiseplan.config.loader.prepare_configapplies it before validation.transit_minuteson a point, port, line or area: the actual minutes of the transit into it, replacing distance / speed (distance and positions unchanged; the transit’s planned minutes are kept, and its vessel speed is shown as distance /transit_minutes). Ignored with a warning when there is no transit into the operation.Text and TeX forecasts state the anchoring rule applied (
% Anchor =line, a line under the TeX title).water_depthaccepts the fill value-9999.0;enrich --add-depthswrites it where no depth can be looked up and retries it on the next run. The enriched YAML recordsbathymetry_provenance(source, file, found, depths from source, depths filled).Provenance in outputs: NetCDF global attributes (all files)
cruiseplan_version,source_config,source_config_sha256,bathymetry_source, planning parameters anddate_created(UTC,Z); the same fields as%comments at the top of the TeX tables and in a Provenance section of the HTML report.Fill-duration markers:
ActivityRecord.duration_is_fill; NetCDFduration_fill_flagwithfill_duration_count; CSVDuration notecolumn;(fill)in HTML and TeX durations.utils.coordinates.ddm_parts,utils.coordinates.distance_nm(one haversine; the KML, LaTeX and timeline distances use it).data.bathymetry.shared_bathymetryandget_bathymetry_manager:runopens each bathymetry file once.Stations expanded from a line operation carry a
historyfield recording their origin (the point model now has ahistoryfield).Fill-duration summary line (count,
N x 999 h, and the schedule total excluding fills) in the WARNING log and at the top of the HTML and TeX reports, so the inflated fill hours do not hide the real total.
Changed
Documentation: units table in the YAML reference;
buffer_time_minutesis applied (one block per leg after the last operation, before the transit to the arrival port), not “stored only”;turnaround_time_minutesis added to depth-based CTD casts only; migration page for 0.6.0.Test fixture
coldsnap-2028-newformat.yaml(every activity listed twice) is kept ascoldsnap-2028-newformat_old.yaml;mooring_sequence_greenland.yamllists each activity once (84 rows, 377 h).forecast --start-index: the row at the index starts at--start-time(UTC). On an operation row the transit into it is not included; on a transit row the ship is starting that transit now (it is kept, starting at--start-time). With--current-positionthe position wins: a transit row moves to the operation it leads to, and--start-timeis the time at that position. The text and TeX headers state the rule applied.NetCDF
creation_dateis UTC withZ(was naive local time).The library no longer configures logging: API functions do not call
logging.basicConfig(it reset the caller’s root handlers). Thecruiseplancommand line configures logging;verbose=Truesets thecruiseplanlogger to DEBUG for that call only. Scripts and notebooks that want the INFO messages configure logging themselves (logging.basicConfig(level=logging.INFO)).Bathymetry download and station-picker status messages go through
logginginstead ofprint. Log messages carry no emoji.
Removed
CoordConverter.decimal_degrees_to_ddm(did not carry 60 minutes into the degrees); useutils.coordinates.ddm_parts.cruiseplan.timeline.routing(optimize_composite_route, never called).cruiseplan.utils.logging.configure_loggingandget_logger.CONVENTIONS.md; code conventions and naming are in the developer guide.
0.5.0 - 2026-11-02
Breaking changes
Python 3.10 is no longer supported; minimum is 3.11. Classifiers list 3.11–3.13.
Added
CHANGELOG.md; breaking-change notes moved here from the README.testoptional-dependency group (pytest, pytest-cov, pyyaml);devincludes it.cruiseplan.runtime.operations.DurationRules: protocol for the rules object passed tocalculate_duration.
Changed
Documentation updates: developer guide, YAML reference, workflows (#159).
Dependencies declared in
pyproject.tomlonly; CI gates coverage at 70 %;CITATION.cffat v0.4.0 (#169).CI: Ubuntu tests Python 3.11–3.13; macOS and Windows test 3.11 only; separate lint (
ruff check,ruff format --check) and coverage jobs.Ruff ruleset aligned with the sibling packages (ctdcast): annotations, numpy docstrings with all parameters documented, pathlib, bugbear, blind-except.
cruiseplan/outputis now linted (an unanchoredoutput/in.gitignorehad excluded it).Re-raised errors carry the original exception as
__cause__. Some broadexcept Exceptionblocks are narrowed (OSErrorfor directory checks;ValueError/TypeErrorfor NetCDF value andstart_timeparsing); other exception types from those calls now propagate instead of being wrapped or ignored.
Removed
requirements.txtandrequirements-dev.txt(#169).Invalid
schedule.dayin the Dependabot config (#169).CI workaround for building
ruamel.yaml.clibz; ruamel.yaml 0.19 only pulls it in through an optional extra.environment.yml; the docs workflows create their environment (Python, pip, pandoc) inline and install.[dev].
0.4.0 - 2026-08-04
Added
cruiseplan run(#157),cruiseplan list(#149).Station plan for use on board, later renamed
forecast(#82, #93); glider and yo-yo operations (#93).EEZ boundaries on interactive (#94) and static PNG maps (#154, #156).
Map options
--max-depth,--no-title,--no-legend,--no-labels(#108, #117).Multi-segment section expansion (#122).
Changed
Breaking:
cruiseplan stationplanrenamed tocruiseplan forecast(#149).Breaking: modules renamed
cruiseplan.schema→cruiseplan.config,cruiseplan.core→cruiseplan.runtime,cruiseplan.calculators→cruiseplan.timeline(#66). Earlier README notes listed this under v0.3.6, which was never tagged.Breaking: package
__init__modules no longer re-export; import from the defining module (#67).Breaking: minimum Python is 3.10 (#118).
CLI rebuilt around
build_parser+runwith a positional config argument (#146); CLI and API defaults made consistent (#119, #120); shared error handler and verbose logging (#121); CLI output and--formatcleanup (#145).CLI reference rewritten (#151, #153).
Fixed
Custom ports and leg-only schedules (#70).
distance_to_nextin the scheduler (#94).buffer_timehandling (#152).
0.3.5 - 2026-01-17
Changed
__init__.pycontents moved into thecruiseplan.apimodule (#63).schema/files renamed (#64).cruiseplan stationshas an API counterpart (#65).
0.3.4 - 2026-01-12
Changed
Breaking: point/line/area keys and defaults extracted into
vocabulary.py(#61).Canonical YAML structure (#62).
0.3.3 - 2026-01-11
Changed
Breaking: YAML uses
transects:(wastransits:) for line operations (#59) andwaypoints:(wasstations:) for point operations (#60).
0.3.2 - 2026-01-10
Changed
enrichandvalidateprocessing reorganized (#58); utils module reorganized (#56); further CLI abstraction (#55); validation module refactored (#53); ruff cleanup (#54).
0.3.1 - 2026-01-04
Changed
Unified point operation; outputs updated (#52).
Fixed
Scheduler bugs (#52).
0.3.0 - 2026-01-04
Changed
CLI separated from the API (#43, #44); validation and scheduler utilities refactored (#42).
position.latitudereplaced bylatitude;GeoPoint/FlexibleLocationModel(#41).Breaking: bathymetry flags shortened
--bathymetry-*→--bathy-*(#45).
Removed
Breaking:
cruiseplan downloadandcruiseplan pandoi(#45).
0.2.2 - 2025-12-22
Added
Python API for notebook use, parallel to the CLI (#38).
Cruises without explicit legs (#39).
0.2.1 - 2025-12-21
Added
cruiseplan process(#37).
Fixed
LaTeX generator bug (#37).
0.2.0 - 2025-12-20
Added
GEBCO 2025 bathymetry (#22); CTD section expansion (#24); buffer time (#25); DOI search (#28); map generators and demo notebook (#29, #34).
Changed
YAML handling switched from PyYAML to ruamel.yaml to preserve comments (#26).
Timeline, activities and maps reworked (#30, #31).
0.1.0 - 2025-12-12
First release on PyPI.