CESQL v1 release notes (cloudevents#1298)

* docs: add release note for CESQL v1 Signed-off-by: Calum Murray <[email protected]> * docs: add link to cesql v1 release notes to RELEASES.md Signed-off-by: Calum Murray <[email protected]> * fix: order by release date instead of group Signed-off-by: Calum Murray <[email protected]> * Address review comments * Add link to cesql v1 in releases table * Add short paragraph to cesql README Signed-off-by: Calum Murray <[email protected]> --------- Signed-off-by: Calum Murray <[email protected]> Signed-off-by: Doug Davis <[email protected]>
duglin · Jun 17, 2024 · 1c7cb11 · 1c7cb11
1 parent 6e6e665
commit 1c7cb11
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 16 deletions.
diff --git a/README.md b/README.md
@@ -57,10 +57,10 @@ and a graduated project on [Jan 25, 2024](https://github.com/cncf/toc/pull/996)
 | [Proprietary Specifications](cloudevents/proprietary-specs.md) | -                                                                               | [Not versioned](cloudevents/proprietary-specs.md)     |
 
 ## Other Specifications
-|                 | Latest Release | Working Draft                 |
-| :-------------- | :------------: | :---------------------------: |
-| CE SQL          |       -        | [WIP](cesql/spec.md)          |
-| Subscriptions   |       -        | [WIP](subscriptions/spec.md)  |
+|                 | Latest Release                                                  | Working Draft                 |
+| :-------------- | :-------------------------------------------------------------: | :---------------------------: |
+| CE SQL          | [v1.0.0](https://github.com/cloudevents/spec/tree/cesql/v1.0.0/cesql) | [WIP](cesql/spec.md)          |
+| Subscriptions   |                                 -                               | [WIP](subscriptions/spec.md)  |
 
 The Registry and Pagination specifications can now be found in the
 [xRegistry/spec](https://github.com/xregistry/spec) repo.

diff --git a/cesql/README.md b/cesql/README.md
@@ -1,3 +1,7 @@
-# CloudEvents SQL Expression Language - Version 1.0
+# CloudEvents SQL Expression Language - Version 1.0.0
 
-See the [CESQL specification](spec.md).
+CloudEvents SQL expressions (also known as CESQL) allow computing values and
+matching of CloudEvent attributes against complex expressions that lean on the
+syntax of Structured Query Language (SQL) `WHERE` clauses.
+
+For more information, see the [CESQL specification](spec.md).
diff --git a/cesql/RELEASE_NOTES.md b/cesql/RELEASE_NOTES.md
@@ -2,5 +2,24 @@
 
 <!-- no verify-specs -->
 
-## vX.Y.Z - YYYY/MM/DD
-- None yet (#000)
+## v1.0.0 - 2024/06/13
+This is the v1 release of the specification! CESQL v1 provides users with the
+ability to write and execute queries against CloudEvents. This allows for
+computing values and matchins of CloudEvent attributes against complex
+expressions that lean on the syntax of Structured Query Language (SQL).
+
+Notable changes between the WIP draft and the v1 specification are:
+- Specify error types
+- Clarify return values of expressions that encounter errors
+- Clarify that missing attributes result in an error and the expression
+  returning it's default value
+- Add support for boolean to integer and integer to boolean type casting
+- Clarify the order of operations
+- Clarify how user defined functions work
+- Define the default "zero" values for the built in types
+- Clarify that string comparisons are case sensitive
+- Specify which characters are treated as whitespace for the TRIM function
+- Specify that functions must still return values along with errors, as well as
+  the behaviour when user defined function do not do this correctly
+- For the fail fast error handling mode, expressions now return the zero value
+  for their return type when they encounter an error, rather than undefined
diff --git a/docs/RELEASES.md b/docs/RELEASES.md
@@ -1,11 +1,12 @@
 # CloudEvents Releases
 
-| Specification Group | Version | Release Date | Release Notes |
-| :------------------ | :-----: | :----------- | :-----------: |
-| CloudEvents         | [1.0.2](https://github.com/cloudevents/spec/tree/v1.0.2/cloudevents) | 2022/02/05 | [Notes](../cloudevents/RELEASE_NOTES.md#v102---20220205) |
-| CloudEvents         | [1.0.1](https://github.com/cloudevents/spec/tree/v1.0.1) | 2020/12/12 | [Notes](../cloudevents/RELEASE_NOTES.md#v101---20201212) |
-| CloudEvents         | [1.0](https://github.com/cloudevents/spec/tree/v1.0) | 2019/10/24 | [Notes](../cloudevents/RELEASE_NOTES.md#v100---20191024) |
-| CloudEvents         | [0.3](https://github.com/cloudevents/spec/tree/v0.3) | 2019/06/13 | [Notes](../cloudevents/RELEASE_NOTES.md#v03---20190613) |
-| CloudEvents         | [0.2](https://github.com/cloudevents/spec/tree/v0.2) | 2018/12/06 | [Notes](../cloudevents/RELEASE_NOTES.md#v02---20181206) |
-| CloudEvents         | [0.1](https://github.com/cloudevents/spec/tree/v0.1) | 2018/04/20 | [Notes](../cloudevents/RELEASE_NOTES.md#v01---20180420) |
+| Specification Group | Version                                                              | Release Date | Release Notes                                            |
+| :------------------ | :------------------------------------------------------------------: | :----------- | :------------------------------------------------------: |
+| CESQL               | [1.0.0](https://github.com/cloudevents/spec/tree/cesql/v1.0.0)         | 2024/06/13   | [Notes](../cesql/RELEASE_NOTES.md#v100---20240613)       |
+| CloudEvents         | [1.0.2](https://github.com/cloudevents/spec/tree/v1.0.2/cloudevents) | 2022/02/05   | [Notes](../cloudevents/RELEASE_NOTES.md#v102---20220205) |
+| CloudEvents         | [1.0.1](https://github.com/cloudevents/spec/tree/v1.0.1)             | 2020/12/12   | [Notes](../cloudevents/RELEASE_NOTES.md#v101---20201212) |
+| CloudEvents         | [1.0](https://github.com/cloudevents/spec/tree/v1.0)                 | 2019/10/24   | [Notes](../cloudevents/RELEASE_NOTES.md#v100---20191024) |
+| CloudEvents         | [0.3](https://github.com/cloudevents/spec/tree/v0.3)                 | 2019/06/13   | [Notes](../cloudevents/RELEASE_NOTES.md#v03---20190613)  |
+| CloudEvents         | [0.2](https://github.com/cloudevents/spec/tree/v0.2)                 | 2018/12/06   | [Notes](../cloudevents/RELEASE_NOTES.md#v02---20181206)  |
+| CloudEvents         | [0.1](https://github.com/cloudevents/spec/tree/v0.1)                 | 2018/04/20   | [Notes](../cloudevents/RELEASE_NOTES.md#v01---20180420)  |