fix planning issue 4226

3.4/aql/functions-date.md

@@ -1,6 +1,7 @@
 ---
 layout: default
-description: AQL offers functionality to work with dates
+description: AQL offers functionality to work with dates as numeric timestamps and as ISO 8601 date time strings
+title: AQL Date Functions
 ---
 Date functions
 ==============
@@ -14,35 +15,42 @@ all non leap seconds beginning with January 1st 1970 00:00:00.000 UTC, also know
 the Unix epoch. A point in time is called timestamp. A timestamp has the same value
 at every point on earth. The date functions use millisecond precision for timestamps.
 
-time unit definitions
+Time unit definitions:
 
-* millisecond: 1/1000 of a second
-* second: one [SI second](https://www.bipm.org/en/publications/si-brochure/second.html){:target="_blank"}
-* Minute: one minute is defined as 60 seconds
-* Hour: one hour is defined as 60 minutes
-* day: one day is defined as 24 hours
-* week: one week is defined as 7 days
-* year: one year is defined as 365.2425 days
-* month: one month is defined as 1/12 of a year
+- **millisecond**: 1/1000 of a second
+- **second**: one [SI second](https://www.bipm.org/en/publications/si-brochure/second.html){:target="_blank"}
+- **minute**: one minute is defined as 60 seconds
+- **hour**: one hour is defined as 60 minutes
+- **day**: one day is defined as 24 hours
+- **week**: one week is defined as 7 days
+- **month**: one month is defined as 1/12 of a year
+- **year**: one year is defined as 365.2425 days
 
 All functions that require dates as arguments accept the following input values:
 
-- numeric timestamps, millisecond precision;
- An example timestamp value is *1399472349522*, which translates to
- *2014-05-07T14:19:09.522Z*.
+- **numeric timestamps**, millisecond precision.
+
+ An example timestamp value is `1399472349522`, which translates to
+ `2014-05-07T14:19:09.522Z`.
+
+- **date time strings** in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601){:target="_blank"} format:
+ - `YYYY-MM-DDTHH:MM:SS.MMM`
+ - `YYYY-MM-DD HH:MM:SS.MMM`
+ - `YYYY-MM-DD`
+
+ Milliseconds (`.MMM`) are always optional. Two digits for the hours (`HH`),
+ minutes (`MM`) and seconds (`SS`) are mandatory, i.e. zero-padding is required
+ for the values 0 through 9 (e.g. `05` instead of `5`). Leading zeroes for the
+ year (`YYYY`), month (`MM`) and day (`DD`) can be left out, but is discouraged.
 
-- date time strings in formats *YYYY-MM-DDTHH:MM:SS.MMM*,
- *YYYY-MM-DD HH:MM:SS.MMM* or *YYYY-MM-DD*; Milliseconds are always optional.
  A time offset may optionally be added at the end of the string, with the
  hours and minutes that need to be added or subtracted to the date time value.
- For example, *2014-05-07T14:19:09+01:00* can be used to specify a one hour offset,
- and *2014-05-07T14:19:09+07:30* can be specified for seven and half hours offset.
- Negative offsets are also possible. Alternatively to an offset, a *Z* can be used
- to indicate UTC / Zulu time.
-
- An example value is *2014-05-07T14:19:09.522Z* meaning May 7th 2014, 14:19:09 and
- 522 milliseconds, UTC / Zulu time. Another example value without time component is
- *2014-05-07Z*.
+ For example, `2014-05-07T14:19:09+01:00` can be used to specify a one hour offset,
+ and `2014-05-07T14:19:09+07:30` can be specified for seven and half hours offset.
+ Negative offsets are also possible. Alternatively to an offset, a `Z` can be used
+ to indicate UTC / Zulu time. An example value is `2014-05-07T14:19:09.522Z`
+ meaning May 7th 2014, 14:19:09 and 522 milliseconds, UTC / Zulu time.
+ Another example value without time component is `2014-05-07Z`.
 
 ```js
 DATE_HOUR( 2 * 60 * 60 * 1000 ) // 2

3.4/release-notes-upgrading-changes34.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-description: It is recommended to check the following list of incompatible changes beforeupgrading to ArangoDB 3
+description: It is recommended to check the following list of incompatible changes before upgrading to ArangoDB 3.4
 ---
 Incompatible changes in ArangoDB 3.4
 ====================================
@@ -393,9 +393,36 @@ The following APIs have been added or augmented:
 AQL
 ---
 
+- all AQL date functions in 3.4 may raise an "invalid date value" warning when given a
+ syntactically invalid date string as an input. The rules for valid date strings have been
+ made more strict in ArangoDB 3.4.
+
+ In previous versions, passing in a date value with a one-digit hour, minute or second
+ component worked just fine, and the date was considered valid.
+
+ From ArangoDB 3.4 onwards, using date values with a one-digit hour, minute or second
+ component will render the date value invalid, and make the underlying date functions
+ return a value of `null` and issue an "invalid date value" warning.
+
+ The following overview details which values are considered valid and invalid in the
+ respective ArangoDB versions:
+
+ | Date string | 3.3 | 3.4 |
+ |-------------------------|-------|-------------|
+ | `"2019-07-01 05:02:34"` | valid | valid |
+ | `"2019-7-1 05:02:34"` | valid | valid |
+ | `"2019-7-1 5:02:34"` | valid | **invalid** |
+ | `"2019-7-1 05:2:34"` | valid | **invalid** |
+ | `"2019-7-1 05:02:4"` | valid | **invalid** |
+ | `"2019-07-01T05:02:34"` | valid | valid |
+ | `"2019-7-1T05:02:34"` | valid | valid |
+ | `"2019-7-1T5:02:34"` | valid | **invalid** |
+ | `"2019-7-1T05:2:34"` | valid | **invalid** |
+ | `"2019-7-1T05:02:4"` | valid | **invalid** |
+
 - the AQL functions `CALL` and `APPLY` may now throw the errors 1540
-(`ERROR_QUERY_FUNCTION_NAME_UNKNOWN`) and 1541 (`ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH`)
-instead of error 1582 (`ERROR_QUERY_FUNCTION_NOT_FOUND`) in some situations.
+ (`ERROR_QUERY_FUNCTION_NAME_UNKNOWN`) and 1541 (`ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH`)
+ instead of error 1582 (`ERROR_QUERY_FUNCTION_NOT_FOUND`) in some situations.
 
 - the existing "fulltext-index-optimizer" optimizer rule has been removed 
  because its duty is now handled by the new "replace-function-with-index" rule.

3.5/aql/functions-date.md

@@ -1,6 +1,7 @@
 ---
 layout: default
-description: AQL offers functionality to work with dates
+description: AQL offers functionality to work with dates as numeric timestamps and as ISO 8601 date time strings
+title: AQL Date Functions
 ---
 Date functions
 ==============
@@ -14,35 +15,42 @@ all non leap seconds beginning with January 1st 1970 00:00:00.000 UTC, also know
 the Unix epoch. A point in time is called timestamp. A timestamp has the same value
 at every point on earth. The date functions use millisecond precision for timestamps.
 
-time unit definitions
+Time unit definitions:
 
-* millisecond: 1/1000 of a second
-* second: one [SI second](https://www.bipm.org/en/publications/si-brochure/second.html){:target="_blank"}
-* Minute: one minute is defined as 60 seconds
-* Hour: one hour is defined as 60 minutes
-* day: one day is defined as 24 hours
-* week: one week is defined as 7 days
-* year: one year is defined as 365.2425 days
-* month: one month is defined as 1/12 of a year
+- **millisecond**: 1/1000 of a second
+- **second**: one [SI second](https://www.bipm.org/en/publications/si-brochure/second.html){:target="_blank"}
+- **minute**: one minute is defined as 60 seconds
+- **hour**: one hour is defined as 60 minutes
+- **day**: one day is defined as 24 hours
+- **week**: one week is defined as 7 days
+- **month**: one month is defined as 1/12 of a year
+- **year**: one year is defined as 365.2425 days
 
 All functions that require dates as arguments accept the following input values:
 
-- numeric timestamps, millisecond precision;
- An example timestamp value is *1399472349522*, which translates to
- *2014-05-07T14:19:09.522Z*.
+- **numeric timestamps**, millisecond precision.
+
+ An example timestamp value is `1399472349522`, which translates to
+ `2014-05-07T14:19:09.522Z`.
+
+- **date time strings** in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601){:target="_blank"} format:
+ - `YYYY-MM-DDTHH:MM:SS.MMM`
+ - `YYYY-MM-DD HH:MM:SS.MMM`
+ - `YYYY-MM-DD`
+
+ Milliseconds (`.MMM`) are always optional. Two digits for the hours (`HH`),
+ minutes (`MM`) and seconds (`SS`) are mandatory, i.e. zero-padding is required
+ for the values 0 through 9 (e.g. `05` instead of `5`). Leading zeroes for the
+ year (`YYYY`), month (`MM`) and day (`DD`) can be left out, but is discouraged.
 
-- date time strings in formats *YYYY-MM-DDTHH:MM:SS.MMM*,
- *YYYY-MM-DD HH:MM:SS.MMM* or *YYYY-MM-DD*; Milliseconds are always optional.
  A time offset may optionally be added at the end of the string, with the
  hours and minutes that need to be added or subtracted to the date time value.
- For example, *2014-05-07T14:19:09+01:00* can be used to specify a one hour offset,
- and *2014-05-07T14:19:09+07:30* can be specified for seven and half hours offset.
- Negative offsets are also possible. Alternatively to an offset, a *Z* can be used
- to indicate UTC / Zulu time.
-
- An example value is *2014-05-07T14:19:09.522Z* meaning May 7th 2014, 14:19:09 and
- 522 milliseconds, UTC / Zulu time. Another example value without time component is
- *2014-05-07Z*.
+ For example, `2014-05-07T14:19:09+01:00` can be used to specify a one hour offset,
+ and `2014-05-07T14:19:09+07:30` can be specified for seven and half hours offset.
+ Negative offsets are also possible. Alternatively to an offset, a `Z` can be used
+ to indicate UTC / Zulu time. An example value is `2014-05-07T14:19:09.522Z`
+ meaning May 7th 2014, 14:19:09 and 522 milliseconds, UTC / Zulu time.
+ Another example value without time component is `2014-05-07Z`.
 
 ```js
 DATE_HOUR( 2 * 60 * 60 * 1000 ) // 2

3.5/release-notes-upgrading-changes34.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-description: It is recommended to check the following list of incompatible changes beforeupgrading to ArangoDB 3
+description: It is recommended to check the following list of incompatible changes before upgrading to ArangoDB 3.4
 ---
 Incompatible changes in ArangoDB 3.4
 ====================================
@@ -393,9 +393,36 @@ The following APIs have been added or augmented:
 AQL
 ---
 
+- all AQL date functions in 3.4 may raise an "invalid date value" warning when given a
+ syntactically invalid date string as an input. The rules for valid date strings have been
+ made more strict in ArangoDB 3.4.
+
+ In previous versions, passing in a date value with a one-digit hour, minute or second
+ component worked just fine, and the date was considered valid.
+
+ From ArangoDB 3.4 onwards, using date values with a one-digit hour, minute or second
+ component will render the date value invalid, and make the underlying date functions
+ return a value of `null` and issue an "invalid date value" warning.
+
+ The following overview details which values are considered valid and invalid in the
+ respective ArangoDB versions:
+
+ | Date string | 3.3 | 3.4 |
+ |-------------------------|-------|-------------|
+ | `"2019-07-01 05:02:34"` | valid | valid |
+ | `"2019-7-1 05:02:34"` | valid | valid |
+ | `"2019-7-1 5:02:34"` | valid | **invalid** |
+ | `"2019-7-1 05:2:34"` | valid | **invalid** |
+ | `"2019-7-1 05:02:4"` | valid | **invalid** |
+ | `"2019-07-01T05:02:34"` | valid | valid |
+ | `"2019-7-1T05:02:34"` | valid | valid |
+ | `"2019-7-1T5:02:34"` | valid | **invalid** |
+ | `"2019-7-1T05:2:34"` | valid | **invalid** |
+ | `"2019-7-1T05:02:4"` | valid | **invalid** |
+
 - the AQL functions `CALL` and `APPLY` may now throw the errors 1540
-(`ERROR_QUERY_FUNCTION_NAME_UNKNOWN`) and 1541 (`ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH`)
-instead of error 1582 (`ERROR_QUERY_FUNCTION_NOT_FOUND`) in some situations.
+ (`ERROR_QUERY_FUNCTION_NAME_UNKNOWN`) and 1541 (`ERROR_QUERY_FUNCTION_ARGUMENT_TYPE_MISMATCH`)
+ instead of error 1582 (`ERROR_QUERY_FUNCTION_NOT_FOUND`) in some situations.
 
 - the existing "fulltext-index-optimizer" optimizer rule has been removed 
  because its duty is now handled by the new "replace-function-with-index" rule.