From 3d86731dc5fb30d581c2af2a98790f1c457daecd Mon Sep 17 00:00:00 2001 From: dandelany Date: Mon, 9 Sep 2024 19:01:48 -0700 Subject: [PATCH] write 2.19.0 upgrade guide --- docs/upgrade-guides/2-18-0-to-2-19-0.md | 41 +++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/upgrade-guides/2-18-0-to-2-19-0.md b/docs/upgrade-guides/2-18-0-to-2-19-0.md index 04209fe..15cfe3a 100644 --- a/docs/upgrade-guides/2-18-0-to-2-19-0.md +++ b/docs/upgrade-guides/2-18-0-to-2-19-0.md @@ -2,3 +2,44 @@ This document describes the upgrade instructions from `2.18.0` to `2.19.0`. +## Procedural Scheduling +Aerie `2.19.0` includes our Procedural Scheduling feature, which is a new way to write scheduling goals in Java. The documentation has been updated and reorganized to describe this new feature, see [Scheduling & Constraints](https://nasa-ammos.github.io/aerie-docs/scheduling-and-constraints/introduction/) for more details. + +This is an early-release feature which may see some significant changes in future releases as we refine the idea - please feel free to submit feedback via [Github issues](https://github.com/NASA-AMMOS/aerie/issues) or our [#nasa-ammos-aerie-users Slack channel](https://jpl.slack.com/archives/C0163E42UBF) if you have questions or issues. + +## DB Migrations +Two new database migrations have been added to support Procedural Scheduling. If you are upgrading from a past version and want to preserve your data, follow the instructions in the +[Database Migrations Guide](../deployment/advanced-database-migrations.mdx) to apply migrations after upgrading. Make sure to either pass the `--all` flag, or apply **both** migrations interactively. + +## Scheduling plan spec schema refactor (breaking change) + +The primary key for `scheduling_specification_goals` has been updated to a new unique auto-incrementing integer: `goal_invocation_id`. This is to allow multiple "invocations" of the same goal definition in a plan spec. + +This is only a breaking change if you were directly querying (through the API) the following tables: +- `scheduling_specification_goals` +- `scheduling_goal_analysis` +- `scheduling_goal_analysis_created_activies` +- `scheduling_goal_analysis_satisfying_activies` + +If you were making these queries, take note of the following details to update your code: + +GQL queries using `by_pk` against related tables, e.g. `scheduling_specification_goals_by_pk`, will need to be updated to use `goal_invocation_id`'s, or to use a non `by_pk` query and handle multiple goal invocations being returned. + +Similarly, tables relating to scheduling analyses (`scheduling_goal_analysis`, `scheduling_goal_analysis_created_activities`, `scheduling_goal_analysis_satisfying_activities`) now store the `goal_invocation_id` of the specific invocation they're related to, and use this as part of their primary key, again so they can reference specific invocations of a goal, not just a single `goal_id` in an analysis. They also directly reference the `goal_analysis` table by foreign key instead of each referencing a `goal_definition`, since again, we can now have multiple `goal_analysis` entries for a given `goal_definition` in a scheduler run. + +# New fields on `goal_definition` (non-breaking change) + +`goal_definition` entries now have several new fields to support procedural scheduling: + +```sql +type scheduler.goal_type not null default 'EDSL', -- can be 'EDSL' or 'JAR' +definition text, -- will be null if type is 'JAR', otherwise is traditional EDSL code +uploaded_jar_id integer, -- will be null when type is 'EDSL', otherwise references uploaded procedure jar +parameter_schema jsonb, -- auto populated by Aerie system based on annoations in procedure source code +``` + +You will only need to populate these new fields if adding procedural goals through the API. The UI and CLI have already been updated. + +Arguments that will be passed to a specific goal invocation table live a in a new field `arguments jsonb` in the `scheduling_specification_goals` table. + +The `goal_analysis` also now stores the "as-run" arguments that were passed to a invocation in a new field `arguments jsonb`, so they can be referenced when reviewing analyses.