write upgrade guide for v4.1.0

Author: dandelany

docs/upgrade-guides/4-0-0-to-4-1-0.md

@@ -2,3 +2,47 @@
 
 This document describes the upgrade instructions from `4.0.0` to `4.1.0`.
 
+## Configuration changes
+
+### Cookie forwarding for actions
+
+New **optional** environment variables have been added to support forwarding browser cookies (e.g., SSO session tokens) to **actions** as secrets. If you do not need this feature, no changes are required. To enable cookie forwarding, you must add the following to your docker-compose file:
+
+```yaml
+aerie_ui:
+  environment:
+    PUBLIC_ACTION_INCLUDE_CREDENTIALS: 'true'  # include browser cookies in action server requests
+
+aerie_action:
+  environment:
+    ACTION_COOKIE_NAMES: 'ssosession'  # comma-separated list of cookie names to forward
+    ACTION_CORS_ALLOWED_ORIGIN: 'https://YOUR_HOST_NAME'  # origin of your PlanDev UI (required for cross-origin)
+```
+
+Forwarded cookies are available in action code under actionsAPI.config.SECRETS.cookies:
+
+```js
+const ssoToken = actionsAPI.config.SECRETS.cookies.ssosession;
+```
+
+See the [Actions documentation](/sequencing/actions/#accessing-secrets-in-actions) for more details on cookie requirements and secrets in actions.
+
+## Other changes
+
+### PlanDev: Fixed issues with procedure generation
+PlanDev v4.0.0 contained some regressions with procedural constraints and goals - namely, some `static` fields were incorrectly being included as procedure parameters in the JAR, and the JAR was incorrectly named `<NAME>Mapper.jar` instead of just `<NAME>.jar`. These have both been fixed in this release
+
+### SeqDev: `.seq.json` filetype association
+
+For the SeqDev editor, we have changed the default association for `.seq.json` files so they are edited as `JSON` files rather than `sequence` files, since SeqJson is usually an `outputFormat` rather than an `inputFormat`. However, since this is a user-configurable database setting, existing users will need to update it if they want this change. In Hasura/Postgres, update the table `ui.file_extension_content_type` of the row where `file_extension = .seq.json` to have `content_type` value of `JSON`.
+
+### SeqDev: SeqN language improvements
+
+For SeqDev users, this release includes a new release of the [aerie-sequence-languages](https://github.com/NASA-AMMOS/aerie-sequence-languages) library ([**v1.0.1**](https://github.com/NASA-AMMOS/aerie-sequence-languages/releases/tag/v1.0.1)), which will only work with SeqDev v4.1.0 (this release) and above. It includes some improvements to handling of control characters and special characters in SeqN strings, and automatic replacement of unsupported "curly quotes" (`“”`) in SeqN documents.
+
+This is a non-breaking API change, but users with **custom sequencing adaptations** should update this library and rebuild/reupload their adaptation. If your sequencing adaptation overrides the list of SeqDev/SeqN extensions or other SeqN parsing code, you may need to make some code changes to take advantage of these improvements. See PRs [#20](https://github.com/NASA-AMMOS/aerie-sequence-languages/pull/20), [#21](https://github.com/NASA-AMMOS/aerie-sequence-languages/pull/21) & [#22](https://github.com/NASA-AMMOS/aerie-sequence-languages/pull/22) for details.
+
+## SeqDev: Known SeqN inconsistency
+
+An existing inconsistency in the SeqN language definition was discovered: escaped special characters like `"\n"` or `"\t"` in metadata **keys** are serialized into SeqJson differently than **values** - values are escaped while keys are "double-escaped". For example, `@METADATA "key\t" "val\t"` in SeqN becomes `"metadata": { "\\t": "\t" }` in SeqJSON. This was left unchanged due to unknown downstream effects, but we may consider changing it in a future release - contact us if you have concerns.
+