Github user aledsage commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/228#discussion_r150817058
--- Diff: guide/ops/upgrades/_blueprints.md ---
@@ -0,0 +1,50 @@
+
+## Upgrading Blueprints and Bundles
+
+You can install and deploy new versions of blueprints at any time.
+Brooklyn tracks multiple versions of the blueprints you install, as can be
seen in the catalog.
+
+
+### Defining and Forcing Upgrade Paths
+
+Bundles can declare what bundles and types they can upgrade,
+and they can also force the removal of installed bundles and types on
startup/rebind.
+Forcing can be useful when upgrading Brooklyn to replace any installed
bundle
+not compatible with the newer version of Brooklyn.
+
+To add these definitions, use the following headers in the bundle's OSGi
`META-INF/MANIFEST.MF`:
+
+* `Brooklyn-Catalog-Force-Remove-Bundles`
+* `Brooklyn-Catalog-Force-Remove-Legacy-Items`
+* `Brooklyn-Catalog-Upgrade-For-Bundles`
+* `Brooklyn-Catalog-Upgrade-For-Types`
+
+The most common patterns are to indicate that a bundle can replace all
previous versions of itself
+and all types thereing with types in the current bundle of the same name,
using:
+
+```
+Brooklyn-Catalog-Upgrade-For-Bundles: *
+```
+
+And you can indicate that previous bundles should be uninstalled, forcing
the above upgrades,
+with:
+
+```
+Brooklyn-Catalog-Force-Remove-Bundles: *
+```
+
+The above items can also take a range syntax, e.g. `"*:[1,2)"` when
releasing a `2.0.0` to restrict to
+versions equal to or greater than `1.0.0` but less than `2.0.0`. (Note
that ranges must be quoted.)
+Entries can also take comma-separated lists, and in the case of
replacements, they can define
+explicit renamed targets using
`sourceNameAndVersionRanges=targetNameAndVersion` entries.
+These fields are defined in full in the
+[`BundleUpgradeParser`'s
javadoc]({{book.url.brooklyn_javadoc}}/org/apache/brooklyn/core/typereg/BundleUpgradeParser.html).
--- End diff --
This is good enough for now, but longer term I think the docs should be the
definitive source of info for this (particularly as we want to target non-java
developers). I guess to limit duplication, the javadoc could point coders at
the docs.
That whole topic needs more thought and discussion, for how we javadoc +
document things!
---
