docs: Update the Blue/Green docs to mention it's possible for the tra…

…nsaction to fail (#24200)

This PR updates the Blue/Green docs to mention if the objects you're
swapping are concurrently modified while a transaction is open, then the
transaction may fail.

It also updates the docs a bit to improve the formatting

### Motivation

Related to https://github.com/MaterializeInc/materialize/issues/24196

### Checklist

- [ ] This PR has adequate test coverage / QA involvement has been duly
considered.
- [ ] This PR has an associated up-to-date [design
doc](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/design/README.md),
is a design doc
([template](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/design/00000000_template.md)),
or is sufficiently small to not require a design.
  <!-- Reference the design in the description. -->
- [ ] If this PR evolves [an existing `$T ⇔ Proto$T`
mapping](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/command-and-response-binary-encoding.md)
(possibly in a backwards-incompatible way), then it is tagged with a
`T-proto` label.
- [ ] If this PR will require changes to cloud orchestration or tests,
there is a companion cloud PR to account for those changes that is
tagged with the release-blocker label
([example](MaterializeInc/cloud#5021)).
<!-- Ask in #team-cloud on Slack if you need help preparing the cloud
PR. -->
- [x] This PR includes the following [user-facing behavior
changes](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/guide-changes.md#what-changes-require-a-release-note):
- Updates user facing docs for Blue/Green deployments to mention failure
cases

doc/user/content/manage/blue-green.md

@@ -24,7 +24,7 @@ primary container for database objects (views, indexes, and materialized
 views), while clusters are the compute resources that will perform view
 maintenance and serve queries.
 
-1. Configure `profiles.yml` to set up the different targets. Use consistent
+2. Configure `profiles.yml` to set up the different targets. Use consistent
 naming across the clusters and schemas that will be deployed together. In this
 example, we'll switch between two targets: `prod` and `prod_deploy`.
     ```yaml
@@ -57,12 +57,12 @@ example, we'll switch between two targets: `prod` and `prod_deploy`.
     target: prod_deploy
     ```
 
-1. Leave your sources in a separate schema (e.g. `public`) and don't touch them.
+3. Leave your sources in a separate schema (e.g. `public`) and don't touch them.
 Instead, define them as `sources` in a `schema.yml` file. Since the same source
 can be shared across your production views and clusters, you won’t need to
 recreate them.
 
-1. Create cluster `prod` and schema `prod` in Materialize and deploy your
+4. Create cluster `prod` and schema `prod` in Materialize and deploy your
 production objects here.
 
 ## Deploying changes to production
@@ -75,7 +75,7 @@ production.
     dbt run --exclude config.materialized:source --target prod_deploy
     ```
 
-1. For multi-cluster deployments, co-locate clusters with dependent views or
+2. For multi-cluster deployments, co-locate clusters with dependent views or
 indexes in the same schema. For instance:
 
     - Schema: prod
@@ -94,10 +94,10 @@ as “caught up”, and you can compare both the `prod` and `prod_deploy` versio
 by viewing the Workflow graph from a common source or other upstream
 Materialization.
 
-1. Perform your end-to-end application tests on `prod_deploy` objects to ensure
+2. Perform your end-to-end application tests on `prod_deploy` objects to ensure
 it is safe to cut over.
 
-1. Use the `SWAP` operation to atomically rename your objects in a way that is
+3. Use the `SWAP` operation to atomically rename your objects in a way that is
 transparent to clients.
     ```sql
     BEGIN;
@@ -106,7 +106,9 @@ transparent to clients.
     COMMIT;
     ```
 
-1. Now that changes are running in `prod` and the legacy version is in
+    {{< note >}}This transaction may fail to commit if the objects are concurrently modified by a separate session. If this occurs you should re-run the transaction.{{</ note >}}
+
+4. Now that changes are running in `prod` and the legacy version is in
 `prod_deploy`, you can drop the prod_deploy compute objects and schema.
     ```sql
     DROP CLUSTER prod_deploy CASCADE;