Merge pull request #434 from FgForrest/dev

New Year's Update Release

.github/workflows/ci-master.yml

@@ -41,11 +41,11 @@ jobs:
 
     - name: Resolve new release version
       id: release_version
-      uses: codacy/git-version@2.7.1
+      uses: lukashornych/semantic-calendar-version@v1.1.3
       with:
         prefix: 'v'
-        minor-identifier: 'feat'
-        major-identifier: '(breaking)' # this should be placed somewhere in the commit message like "feat: (breaking) some message"
+        year_switch_mode: 'OnMinor'
+        minor-identifier: '/feat(?:\\([^)]+\\))?:/'
 
     - name: Setup Java JDK
       uses: actions/setup-java@v3  # setup JDK 17 for building

docker/build.sh

@@ -47,7 +47,7 @@ else
 fi
 
 echo "Tagging as: $IMAGE"
-docker buildx . \
+docker build . \
     --pull \
     --platform linux/amd64 \
     -t "$IMAGE" \

documentation/blog/en/01-origins-of-the-evita-db.md

@@ -1,7 +1,7 @@
 ---
 title: The origins of the evitaDB
 perex: Our company set foot in the e-commerce world around 2010. By that time we were in web development for more than 10 years, starting even before the .com bubble.
-date: '2022-01-12'
+date: '12.1.2022'
 author: 'Ing. Jan Novotný'
 motive: assets/images/01-origins-of-the-evita-db.png
 ---

documentation/blog/en/02-designing-evita-query-language-for-graphql-api.md

@@ -1,7 +1,7 @@
 ---
 title: Designing the Evita Query Language for the GraphQL API
 perex: In evitaDB (like in many other databases), in order to get any data, you need to somehow ask which data you want. The GraphQL language is, however, specific and needs a specific syntax.
-date: '2022-01-12'
+date: '12.1.2022'
 author: 'Lukáš Hornych'
 motive: assets/images/02-designing-evita-query-language-for-graphql-api.png
 ---

documentation/blog/en/03-choosing-http-server.md

@@ -1,7 +1,7 @@
 ---
 title: Choosing HTTP server for evitaDB
 perex: We plan to provide several ways to communicate with evitaDB clients. For that we needed some universal HTTP server that would serve at least most of the requests.
-date: '2022-06-17'
+date: '17.6.2022'
 author: 'Lukáš Hornych, Jan Novotný'
 motive: assets/images/03-choosing-http-server.png
 ---

documentation/blog/en/04-blazing-fast-integration-tests.md

@@ -3,7 +3,7 @@ title: Thousands integrations tests under 30 seconds? Yes, you can.
 perex: |
     A fast test suite is a critical aspect that motivates developers to write more tests and run the suite frequently. 
     The ideal test suite should finish in a matter of seconds or low units of minutes.
-date: '2023-03-25'
+date: '25.3.2023'
 author: 'Ing. Jan Novotný'
 motive: assets/images/04-blazing-fast-integration-tests.png
 proofreading: 'needed'

documentation/blog/en/11-we-are-changing-versioning-scheme.md

@@ -0,0 +1,61 @@
+---
+title: We are changing versioning scheme
+perex: |
+  I have always used the semantic versioning (SemVer) scheme for my projects.  However, after discussing with my friend
+  Lukáš Hornych and conducting further research with the team, we have decided to change the versioning scheme for
+  evitaDB. The new scheme will be a Calendar Versioning. If you are interested in following our debate, read on.
+date: '14.1.2024'
+author: 'Jan Novotný'
+motive: assets/images/11-versioning-scheme.png
+proofreading: 'done'
+---
+
+[Semantic Versioning](https://semver.org/) promises that your users can think about the impact of upgrading to a new
+version of your software. But is this really true? There are numerous articles that argue otherwise - I'd recommend
+[this discussion on Hacker News](https://news.ycombinator.com/item?id=21967879) and especially
+[this blog post](https://sedimental.org/designing_a_version.html).
+
+SemVer brings interesting psychological factors into play. Far too often we see libraries with dozens of minor releases
+that never reach version 1.0. Why not? Maybe the author is afraid to commit to a stable API. Maybe the production
+release looks like too much responsibility. I fell into this trap myself - I was avoiding the 1.0 release until
+I screwed up and while testing the automatic release on GitHub, I accidentally released version 10.1 instead of 0.10.
+And since Maven Central (for good reasons) does not allow to [delete artifacts](https://central.sonatype.org/faq/can-i-change-a-component/),
+we were stuck with it. You might not think this is a big deal, but there are a lot of projects that have fallen into
+this trap, including pretty big names like [ReactNative](https://reactnative.dev/versions),
+[Elm-Language](https://elm-lang.org/news), and there's even a dedicated [website](https://0ver.org/) that tracks
+(or tracked) projects with zero versioning.
+
+On the other hand, there are projects that very quickly increase the major version number to make themselves look more
+mature or up-to-date, or maybe just because they "don't care" about backwards compatibility! One of the most famous
+examples of the versioning battle was the [Chrome vs. Firefox battle](https://sedimental.org/designing_a_version.html#case-study-chrome-vs-firefox)
+for the most significant version number. So - if the major version is more about marketing than actual API stability,
+should we even care about it?
+
+The compatibility guarantee is also a very tricky thing - if your project is popular enough, any change in it that
+somehow affects its behavior will [break someone's code](https://xkcd.com/1172/), even if the API stays the same.
+You will never be able to anticipate other people's expectations and assumptions.
+
+There are also very good and balanced [defenses of the SemVer idea](https://caremad.io/posts/2016/02/versioning-software/)
+that we considered, but in the end we decided to go with calendar versioning, specifically the `YYYY.MINOR.MICRO` variant,
+for the following reasons:
+
+1. no matter how hard we try, we will never be able to guarantee backwards compatibility - unless we have a very
+    thorough test suite that covers all possible use cases, which evitaDB does not and probably never will have (let's be
+    honest)
+2. we commit to trying to maintain backwards compatibility, and if it is knowingly broken, we will mark the release
+    with a "breaking change" label (we already do this at the issue level), and once the project gets out of the
+    "pre-release" stage, we will try to consolidate critical changes into larger milestones.
+3. if only the `MICRO` part changes, you can rest assured that the only changes in the build are fixes that are intended
+    to be backward-compatible.
+4. if the `MINOR` part changes, it means there are new features - you should always check the release notes to see
+    what's new and whether they contain breaking changes or not.
+5. you should always have your own test suite to verify that the new version works for you - if you don't, you shouldn't
+    update the library anyway
+6. the `YYYY` part changes automatically with the first new `MINOR` release of the year - since our library is
+    BSL-licensed, you can easily guess if the library you're using is still BSL-licensed or has already transitioned to
+    Apache License 2.0.
+7. the `YYYY` part also helps you to see how old the version you're using is and easily identify whether we provide
+    security updates and fixes for it or not (if we ever come up with such an offer).
+
+So CalVer makes sense for us and we'll see how it goes. We will be releasing the first version with this schema in
+the next few days.

documentation/publishing/root.cz/03-query-basics/example-query.evitaql

@@ -0,0 +1,19 @@
+query(
+  collection("Product"),
+  filterBy(
+    attributeEquals("status", "ACTIVE"),
+    attributeGreaterThan("battery-life", 10),
+    or(
+      attributeIs("validity", NULL),
+      attributeInRangeNow("validity")
+    )
+  ),
+  orderBy(
+    attributeNatural("orderedQuantity", DESC)
+  ),
+  require(
+    entityFetch(
+      attributeContentAll()
+    )
+  )
+)

documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.evitaql

@@ -0,0 +1,6 @@
+query(
+    collection("Product"),
+    require(
+      attributeHistogram(20, OPTIMIZED, "width")
+    )
+)

documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.evitaql.json.md

@@ -0,0 +1,43 @@
+```json
+{
+  "histograms": {
+    "width": {
+      "buckets": [
+        {
+          "occurrences": 1291,
+          "requested": true,
+          "threshold": 15.90
+        },
+        {
+          "occurrences": 210,
+          "requested": true,
+          "threshold": 97.92
+        },
+        {
+          "occurrences": 1876,
+          "requested": true,
+          "threshold": 179.94
+        },
+        {
+          "occurrences": 531,
+          "requested": true,
+          "threshold": 261.96
+        },
+        {
+          "occurrences": 2,
+          "requested": true,
+          "threshold": 343.98
+        },
+        {
+          "occurrences": 1,
+          "requested": true,
+          "threshold": 426.00
+        }
+      ],
+      "max": 508.00,
+      "min": 15.90,
+      "overallCount": 3911
+    }
+  }
+}
+```

documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.evitaql.string.md

@@ -0,0 +1,3 @@
+```md
+width: [15.90 - 97.92]: 1291, [97.92 - 179.94]: 210, [179.94 - 261.96]: 1876, [261.96 - 343.98]: 531, [343.98 - 426.00]: 2, [426.00 - 508.00]: 1
+```

documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.graphql

@@ -0,0 +1,21 @@
+{
+  queryProduct {
+    extraResults {
+      attributeHistogram {
+        width {
+          min
+          max
+          overallCount
+          buckets(
+            requestedCount: 20
+            behavior: OPTIMIZED
+          ) {
+            threshold
+            occurrences
+            requested
+          }
+        }
+      }
+    }
+  }
+}

documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.graphql.json.md

@@ -0,0 +1,41 @@
+```json
+{
+  "width": {
+    "min": "15.90",
+    "max": "508.00",
+    "overallCount": 3911,
+    "buckets": [
+      {
+        "threshold": "15.90",
+        "occurrences": 1291,
+        "requested": true
+      },
+      {
+        "threshold": "97.92",
+        "occurrences": 210,
+        "requested": true
+      },
+      {
+        "threshold": "179.94",
+        "occurrences": 1876,
+        "requested": true
+      },
+      {
+        "threshold": "261.96",
+        "occurrences": 531,
+        "requested": true
+      },
+      {
+        "threshold": "343.98",
+        "occurrences": 2,
+        "requested": true
+      },
+      {
+        "threshold": "426.00",
+        "occurrences": 1,
+        "requested": true
+      }
+    ]
+  }
+}
+```

documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.rest

@@ -0,0 +1,13 @@
+POST /rest/evita/Product/query
+
+{
+  "require" : {
+    "attributeHistogram" : {
+      "requestedBucketCount" : 20,
+      "behavior" : "OPTIMIZED",
+      "attributeNames" : [
+        "width"
+      ]
+    }
+  }
+}

documentation/user/en/query/requirements/examples/histogram/attribute-histogram-optimized.rest.json.md

@@ -0,0 +1,41 @@
+```json
+{
+  "width": {
+    "max": "508.00",
+    "buckets": [
+      {
+        "threshold": "15.90",
+        "occurrences": 1291,
+        "requested": true
+      },
+      {
+        "threshold": "97.92",
+        "occurrences": 210,
+        "requested": true
+      },
+      {
+        "threshold": "179.94",
+        "occurrences": 1876,
+        "requested": true
+      },
+      {
+        "threshold": "261.96",
+        "occurrences": 531,
+        "requested": true
+      },
+      {
+        "threshold": "343.98",
+        "occurrences": 2,
+        "requested": true
+      },
+      {
+        "threshold": "426.00",
+        "occurrences": 1,
+        "requested": true
+      }
+    ],
+    "min": "15.90",
+    "overallCount": 3911
+  }
+}
+```

documentation/user/en/query/requirements/examples/histogram/attribute-histogram.evitaql

@@ -1,6 +1,6 @@
 query(
     collection("Product"),
     require(
-      attributeHistogram(5, "width", "height")
+      attributeHistogram(20, "width", "height")
     )
 )