write 2.19.0 upgrade guide

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.