move documented-extensions to extensions/README.md

Signed-off-by: Doug Davis <[email protected]>
duglin · Feb 29, 2024 · c859ad5 · c859ad5
1 parent ad2ff88
commit c859ad5
Show file tree

Hide file tree

Showing 13 changed files with 51 additions and 51 deletions.
diff --git a/README.md b/README.md
@@ -53,7 +53,7 @@ and a graduated project on [Jan 25, 2024](https://github.com/cncf/toc/pull/996)
 | CloudEvents Primer                                             | [v1.0.2](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md) | [WIP](cloudevents/primer.md)                          |
 | [CloudEvents Adapters](cloudevents/adapters.md)                | -                                                                               | [Not versioned](cloudevents/adapters.md)              |
 | [CloudEvents SDK Requirements](cloudevents/SDK.md)             | -                                                                               | [Not versioned](cloudevents/SDK.md)                   |
-| [Documented Extensions](cloudevents/documented-extensions.md)  | -                                                                               | [Not versioned](cloudevents/documented-extensions.md) |
+| [Documented Extensions](cloudevents/extensions/README.md)  | -                                                                               | [Not versioned](cloudevents/extensions/README.md) |
 | [Proprietary Specifications](cloudevents/proprietary-specs.md) | -                                                                               | [Not versioned](cloudevents/proprietary-specs.md)     |
 
 ## Other Specifications

diff --git a/cloudevents/documented-extensions.md → cloudevents/extensions/README.md b/cloudevents/documented-extensions.md → cloudevents/extensions/README.md
@@ -1,28 +1,28 @@
 # CloudEvents Extension Attributes
 
-The [CloudEvents specification](spec.md) defines a set of metadata
+The [CloudEvents specification](../spec.md) defines a set of metadata
 attributes that can be used when transforming a generic event into a
 CloudEvent. The list of attributes specified in that document represent the
 minimal set that the specification authors deemed most likely to be used in a
 majority of situations.
 
 This document defines some addition attributes that, while not as commonly used
-as the ones specified in the [CloudEvents specification](spec.md), could
+as the ones specified in the [CloudEvents specification](../spec.md), could
 still benefit from being formally specified in the hopes of providing some
 degree of interoperability. This also allows for attributes to be defined in an
 experimental manner and tested prior to being considered for inclusion in the
-[CloudEvents specification](spec.md).
+[CloudEvents specification](../spec.md).
 
-Implementations of the [CloudEvents specification](spec.md) are not
+Implementations of the [CloudEvents specification](../spec.md) are not
 mandated to limit their use of extension attributes to just the ones specified
 in this document. The attributes defined in this document have no official
 standing and might be changed, or removed, at any time. As such, inclusion of
 an attribute in this document does not need to meet the same level of maturity,
 or popularity, as attributes defined in the
-[CloudEvents specification](spec.md). To be
+[CloudEvents specification](../spec.md). To be
 included in this document, aside from the normal PR review process, the
 attribute needs to have at least two
-[Voting](../docs/GOVERNANCE.md#membership) member organizations stating
+[Voting](../../docs/GOVERNANCE.md#membership) member organizations stating
 their support for its inclusion as comments in the PR. If the author of the PR
 is also a Voting member, then they are allowed to be one of two.
 
@@ -35,17 +35,17 @@ MAY), this usage only applies to events that use the extension.
 Extensions attributes, while not defined by the core CloudEvents specifications,
 MUST follow the same serialization rules as defined by the format and protocol
 binding specifications. See
-[Extension Context Attributes](spec.md#extension-context-attributes)
+[Extension Context Attributes](../spec.md#extension-context-attributes)
 for more information.
 
 ## Known Extensions
 
-- [Auth Context](extensions/authcontext.md)
-- [Dataref (Claim Check Pattern)](extensions/dataref.md)
-- [Distributed Tracing](extensions/distributed-tracing.md)
-- [Expiry Time](extensions/expirytime.md)
-- [Partitioning](extensions/partitioning.md)
-- [Recorded Time](extensions/recordedtime.md)
-- [Sampling](extensions/sampledrate.md)
-- [Sequence](extensions/sequence.md)
-- [Severity](extensions/severity.md)
+- [Auth Context](authcontext.md)
+- [Dataref (Claim Check Pattern)](dataref.md)
+- [Distributed Tracing](distributed-tracing.md)
+- [Expiry Time](expirytime.md)
+- [Partitioning](partitioning.md)
+- [Recorded Time](recordedtime.md)
+- [Sampling](sampledrate.md)
+- [Sequence](sequence.md)
+- [Severity](severity.md)
diff --git a/...nts/languages/he/documented-extensions.md → ...devents/languages/he/extensions/README.md b/...nts/languages/he/documented-extensions.md → ...devents/languages/he/extensions/README.md
@@ -1,2 +1,2 @@
 # CloudEvents Extension Attributes
-מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../documented-extensions.md) לבינתיים.
+מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/README.md) לבינתיים.
diff --git a/cloudevents/languages/he/translations.md b/cloudevents/languages/he/translations.md
@@ -12,6 +12,7 @@
 | /cloudevents/bindings/mqtt-protocol-binding.md |   Ready to start   |       |         |
 | /cloudevents/bindings/nats-protocol-binding.md |   Ready to start   |       |          |
 | /cloudevents/bindings/websockets-protocol-binding.md |   Ready to start   |       |         |
+| /cloudevents/extensions/README.md |   Ready to start   |       |         |
 | /cloudevents/extensions/dataref.md |   Ready to start   |       |          |
 | /cloudevents/extensions/distributed-tracing.md |   Ready to start   |       |         |
 | /cloudevents/extensions/partitioning.md |   Ready to start   |       |        |
@@ -22,11 +23,10 @@
 | /cloudevents/formats/protobuf-format.md |   Ready to start   |       |        |
 | /cloudevents/working-drafts/xml-format.md |   Ready to start   |       |        |
 | /cloudevents/adapters.md |   Ready to start   |       |          |
-| /cloudevents/documented-extensions.md |   Ready to start   |       |         |
 | /cloudevents/http-webhook.md |   Ready to start   |       |         |
 | /cloudevents/primer.md |   Ready to start   |       |          |
 | /cloudevents/proprietary-specs.md |   Ready to start   |       |          |
 | /cloudevents/README.md |   Ready to start   |      |     -     |
 | /cloudevents/RELEASE_NOTES.md |   Ready to start   |       |     -     |
 | /cloudevents/SDK.md |   Ready to start   |       |          |
-| /cloudevents/spec.md |  PR reviewing   |    2022-08-17T17:47:33.778Z   |         |
+| /cloudevents/spec.md |  PR reviewing   |    2022-08-17T17:47:33.778Z   |         |
diff --git a/cloudevents/languages/zh-CN/documented-extensions.md b/cloudevents/languages/zh-CN/documented-extensions.md
diff --git a/cloudevents/languages/zh-CN/extensions/README.md b/cloudevents/languages/zh-CN/extensions/README.md
@@ -0,0 +1,23 @@
+# CloudEvents 扩展属性
+
+[CloudEvents 规范](../spec.md)定义了一系列用来将通用事件转换为CloudEvent的元数据属性。该文档中指定的属性列表代表了作者认为在大多数情况下最可能用到的属性最小集。
+
+在本文档中定义了一些额外的属性。这些属性尽管不像[CloudEvents 规范](../spec.md)中的属性那样常见，但精准使用这些属性，仍能为提高互操作性的程度提供帮助。这种额外属性的机制，同样允许新属性在被纳入到[CloudEvents 规范](../spec.md)之前，能以试验的形式被定义。
+
+[CloudEvents 规范](../spec.md)的实现中不会限制必须使用本文档中提到的那些扩展属性。本文档中定义的扩展属性并不是正式的、稳定的，相反它们可能随时被修改，甚至删除。因此，引入本文档中的这些属性并不需要满足像[CloudEvents 规范](../spec.md)中其它属性那样的成熟度和流行性。要想定义一个收录在本文档中的扩展属性，除了正常的PR检查流程外，还需要至少两名[有投票权的成员](../../../../docs/GOVERNANCE.md#membership)在PR中留言支持。如果这个PR的作者本身就具有投票权，那么只需要另一名成员投票支持即可。
+
+## 使用
+
+任何对扩展属性的支持都不是必要的。当一个扩展属性使用了[RFC 2199](https://www.ietf.org/rfc/rfc2119.txt) 中的关键词（如MUST、SHOULD、MAY等）时，对这些关键词的使用仅适用于使用了这个扩展属性的事件。
+
+扩展属性尽管没有定义在CloudEvents的核心规范中，它们同样必须遵守格式和协议绑定规范中定义的序列化规则。详情请见[扩展上下文属性](../spec.md#extension-context-attributes扩展上下文属性)
+
+## 现有的扩展
+
+- [Dataref (Claim Check Pattern)](../../../extensions/dataref.md)
+- [Distributed Tracing](../../../extensions/distributed-tracing.md)
+- [Expiry Time](../../../extensions/expirytime.md)
+- [Partitioning](../../../extensions/partitioning.md)
+- [Recorded Time](../../../extensions/recordedtime.md)
+- [Sampling](../../../extensions/sampledrate.md)
+- [Sequence](../../../extensions/sequence.md)
diff --git a/cloudevents/languages/zh-CN/primer.md b/cloudevents/languages/zh-CN/primer.md
@@ -269,7 +269,7 @@ CloudEvents 规范不强制要求要使用的特定模式，甚至不要求必
 
 工作组考虑到某些属性不够常见而不能归入上述两个类别，
 但此类属性的良好定义仍会使系统间的互操作性级别受益，
-因此将这些属性放入了“扩展”类别并记录在[扩展文档](../../documented-extensions.md)中，
+因此将这些属性放入了“扩展”类别并记录在[扩展文档](../../extensions/README.md)中，
 本规范定义了这些扩展属性在 CloudEvent 中的显示方式。
 
 在确定提议的属性属于哪个类别时，

diff --git a/cloudevents/languages/zh-CN/spec.md b/cloudevents/languages/zh-CN/spec.md
@@ -369,7 +369,7 @@ CloudEvent 可以包含任意数量的具有不同名称的附加上下文属性
 
 扩展的定义应该完全定义属性的方方面面——例如 它的名称、类型、语义含义和可能的值。
 新的扩展定义应该使用一个足够描述性的名称来减少与其他扩展的名称冲突的机会。
-特别是，扩展作者应该检查[扩展文件](documented-extensions.md)中已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。
+特别是，扩展作者应该检查[扩展文件](extensions/README.md)中已知的扩展集——不仅是可能的名称冲突，还有相同目的冲突的扩展。
 
 许多协议为发送者提供了包含额外元数据的能力，例如作为 HTTP 请求头。
 虽然没有强制要求 CloudEvents 接受者处理和传递它们，

diff --git a/cloudevents/languages/zh-CN/translations.md b/cloudevents/languages/zh-CN/translations.md
@@ -12,6 +12,7 @@
 | /cloudevents/bindings/mqtt-protocol-binding.md |   Ready to start   |       |         |
 | /cloudevents/bindings/nats-protocol-binding.md |   Ready to start   |       |          |
 | /cloudevents/bindings/websockets-protocol-binding.md |   Ready to start   |       |         |
+| /cloudevents/extensions/README.md |   Ready to start   |       |          |
 | /cloudevents/extensions/dataref.md |   Ready to start   |       |          |
 | /cloudevents/extensions/distributed-tracing.md |   Ready to start   |       |         |
 | /cloudevents/extensions/partitioning.md |   Ready to start   |       |        |
@@ -22,11 +23,10 @@
 | /cloudevents/formats/protobuf-format.md |   Ready to start   |       |        |
 | /cloudevents/working-drafts/xml-format.md |   Ready to start   |       |        |
 | /cloudevents/adapters.md |   Ready to start   |       |          |
-| /cloudevents/documented-extensions.md |   Ready to start   |       |         |
 | /cloudevents/http-webhook.md |   Ready to start   |       |         |
 | /cloudevents/primer.md |   Ready to start   |       |          |
 | /cloudevents/proprietary-specs.md |   Ready to start   |       |          |
 | /cloudevents/README.md |   PR reviewing   |   2022-03-26T13:54:11.254Z    |     -     |
 | /cloudevents/RELEASE_NOTES.md |   Ready to start   |       |     -     |
 | /cloudevents/SDK.md |   Ready to start   |       |          |
-| /cloudevents/spec.md |   PR reviewing   |    2022-12-30T08:53:56.534Z   |         |
+| /cloudevents/spec.md |   PR reviewing   |    2022-12-30T08:53:56.534Z   |         |
diff --git a/cloudevents/primer.md b/cloudevents/primer.md
@@ -368,7 +368,7 @@ majority of the cases.
 When the group determines that an attribute is not common enough to fall into
 those two categories but would still benefit from the level of interoperability
 that comes from being well-defined, this repo's
-[documented extensions](documented-extensions.md) provides a shared collaboration
+[documented extensions](extensions/README.md) provides a shared collaboration
 space. Each extension specification defines how it will appear within a CloudEvent.
 Extensions which are documented in this way have no special status,
 and may take breaking changes (including being removed entirely). They are not

diff --git a/cloudevents/spec.md b/cloudevents/spec.md
@@ -486,7 +486,7 @@ The definition of an extension SHOULD fully define all aspects of the
 attribute - e.g. its name, type, semantic meaning and possible values. New
 extension definitions SHOULD use a name that is descriptive enough to reduce the
 chances of name collisions with other extensions. In particular, extension
-authors SHOULD check the [documented extensions](documented-extensions.md)
+authors SHOULD check the [documented extensions](extensions/README.md)
 document for the set of known extensions - not just for possible name conflicts
 but for extensions that might be of interest.
 

diff --git a/docs/GOVERNANCE.md b/docs/GOVERNANCE.md
@@ -160,7 +160,7 @@ The specifications produced will adhere to the following:
   string will always be of the form `X.0`.
 
 Note that these rules do not apply to the
-[documented extensions](../cloudevents/documented-extensions.md).
+[documented extensions](../cloudevents/extensions/README.md).
 
 All versions are tagged from the `main` branch, but the tag only applies to
 the "subject" of the release - the directory containing the information

diff --git a/languages/zh-CN/README.md b/languages/zh-CN/README.md
@@ -44,7 +44,7 @@ CloudEvents 是一个以通用格式来描述事件数据的规范。它提供
 | CloudEvents 入门文档                                             | [v1.0.2](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md) | [WIP](../../cloudevents/languages/zh-CN/primer.md)                          |
 | [CloudEvents 适配器](../../cloudevents/languages/zh-CN/adapters.md)                | -                                                                               | [无版本工作草案](../../cloudevents/languages/zh-CN/adapters.md)              |
 | [CloudEvents SDK 必要条件](../../cloudevents/languages/zh-CN/SDK.md)             | -                                                                               | [无版本工作草案](../../cloudevents/languages/zh-CN/SDK.md)                   |
-| [记录的扩展属性](../../cloudevents/languages/zh-CN/documented-extensions.md)  | -                                                                               | [无版本工作草案](../../cloudevents/languages/zh-CN/documented-extensions.md) |
+| [记录的扩展属性](../../cloudevents/languages/zh-CN/extensions/README.md)  | -                                                                               | [无版本工作草案](../../cloudevents/languages/zh-CN/extensions/README.md) |
 | [专有规范](../../cloudevents/languages/zh-CN/proprietary-specs.md) | -                                                                               | [无版本工作草案](../../cloudevents/languages/zh-CN/proprietary-specs.md)     |
 
 ## 其它规范