docs: active libraries + breaking change policy (#1026)

Author: vbarua

site/docs/community/_config

@@ -0,0 +1,4 @@
+arrange:
+  - index.md
+  - active_libraries.md
+  - powered_by.md

site/docs/community/active_libraries.md

@@ -0,0 +1,23 @@
+---
+title: Active Libraries
+---
+
+# Active Libraries
+
+The following language libraries have active users, with at least one party actively working to maintain and improve each of them:
+
+- [substrait-go](https://github.com/substrait-io/substrait-go)
+- [substrait-java](https://github.com/substrait-io/substrait-java)
+- [substrait-python](https://github.com/substrait-io/substrait-python)
+- [substrait-rs](https://github.com/substrait-io/substrait-rs)
+
+# Inactive Libraries
+
+The following libraries in the ecosystem are currently looking for active contributors:
+
+- [substrait-cpp](https://github.com/substrait-io/substrait-cpp)
+- [substrait-csharp](https://github.com/substrait-io/substrait-csharp)
+- [substrait-js](https://github.com/substrait-io/substrait-js)
+- [substrait-ruby](https://github.com/substrait-io/substrait-ruby)
+
+The Substrait project is always open to contributions and would be happy to work with anyone seeking to improve them.

site/docs/governance.md

@@ -62,6 +62,7 @@ The rules require that a community member registering a negative vote must inclu
 | Process/Governance modifications & actions. This includes promoting new contributors to committer or PMC. | 3                          | PMC            | Mailing List    |
 | Management of `-contrib` repositories including adding repositories and giving write access to them       | 3                          | PMC            | Mailing List    |
 | Format/Specification Modifications (including breaking extension changes)                                 | 2                          | PMC            | Github PR       |
+| Deprecations                                                                                              | 2                          | PMC            | Github PR       |
 | Documentation Updates (formatting, moves)                                                                 | 1                          | PMC            | Github PR       |
 | Typos                                                                                                     | 1                          | Committers     | Github PR       |
 | Non-breaking function introductions                                                                       | 1 (not including proposer) | Committers     | Github PR       |

site/docs/spec/_config

@@ -3,3 +3,4 @@ arrange:
   - specification.md
   - technology_principles.md
   - extending.md
+  - breaking_change_policy.md

site/docs/spec/breaking_change_policy.md

@@ -0,0 +1,24 @@
+---
+title: Breaking Change Policy
+---
+
+# Substrait Breaking Change Policy
+
+Breaking changes proposed to the specification should include an explicit migration strategy when they are proposed. This is based on the assumption that users are operating Substrait in a multi-system, multi-language environment where parallel and synchronous deployments are impossible. Breaking changes should be made so that users can update systems independently and asynchronously.
+
+The migration strategy must be implemented in all [active libraries](../community/active_libraries.md) before the breaking change is implemented.
+
+## Breaking Change Cookbooks
+
+### URI to URN Migration
+
+In [2025](https://github.com/substrait-io/substrait/issues/828), the Substrait community noticed that the values used for `uris` were not consistent within the ecosystem.
+
+To deal with this, a new URN format was [introduced](https://github.com/substrait-io/substrait/issues/856) to replace URIs. To migrate the ecosystem to use URNs, producers were updated to dual write URIs and URNs in plans, and consumers were updated to preferentially consume URNs when available.
+
+This work can be seen in:
+- `substrait-java` Migration [PR](https://github.com/substrait-io/substrait-java/pull/522)
+- `substrait-go` Migration [PR](https://github.com/substrait-io/substrait-go/pull/166)
+- `substrait-python` Migration [PR](https://github.com/substrait-io/substrait-python/pull/114)
+
+Once all libraries could read and write the new URN format, and had been available for a reasonable duration, the old URI format was fully removed.