Merge for 2.28.0 release (#642)

## Usage and product changes

We merge development into master for 2.28.0 release.

.factory/automation.yml

@@ -69,7 +69,7 @@ build:
         curl -L https://github.com/doxygen/doxygen/releases/download/Release_1_10_0/doxygen-1.10.0.linux.bin.tar.gz | tar xzO doxygen-1.10.0/bin/doxygen > /var/tmp/doxygen &&
           sudo mv /var/tmp/doxygen /usr/local/bin/ && sudo chmod +x /usr/local/bin/doxygen
         bazel run @vaticle_dependencies//tool/bazelinstall:remote_cache_setup.sh
-        DOCS_DIRS="java/docs nodejs/docs python/docs rust/docs cpp/docs c/docs csharp/docs"
+        DOCS_DIRS="docs/modules/ROOT/partials/java docs/modules/ROOT/partials/nodejs docs/modules/ROOT/partials/python docs/modules/ROOT/partials/rust docs/modules/ROOT/partials/cpp docs/modules/ROOT/partials/c docs/modules/ROOT/partials/csharp"
         rm -rf $DOCS_DIRS
         tool/docs/update.sh
         git add $DOCS_DIRS
@@ -293,7 +293,7 @@ build:
 
         source tool/test/start-cloud-servers.sh 3 && # use source to receive export vars
           bazel test //python/tests/integration:test_connection --test_env=ROOT_CA=$ROOT_CA --test_output=streamed --jobs=1 &&
-          # TODO currently broken test
+          # TODO #635: currently broken test
           # bazel test //python/tests/integration:test_cloud_failover --test_env=ROOT_CA=$ROOT_CA --test_output=streamed --jobs=1 &&
           export CLOUD_FAILED= || export CLOUD_FAILED=1
         tool/test/stop-cloud-servers.sh
@@ -541,7 +541,7 @@ build:
         export SYNC_DEPENDENCIES_TOKEN=$REPO_GITHUB_TOKEN
         bazel run @vaticle_dependencies//tool/sync:dependencies -- --source ${FACTORY_REPO}@${FACTORY_COMMIT}
 
-# TODO: assembly tests for all drivers to run in factory
+# TODO #512: assembly tests for all drivers to run in factory
 
 release:
   filter:

BUILD

@@ -41,7 +41,7 @@ checkstyle_test(
         ".circleci/windows/git.patch",
         "LICENSE",
         "VERSION",
-        "docs/*",
+        "docs/**/*",
     ]),
     license_type = "apache-header",
 )

RELEASE_NOTES_LATEST.md

@@ -9,7 +9,7 @@ Documentation: https://typedb.com/docs/drivers/rust/overview
 
 
 ```sh
-cargo add [email protected]-rc0
+cargo add [email protected]
 ```
 
 
@@ -29,7 +29,7 @@ Documentation: https://typedb.com/docs/drivers/java/overview
     <dependency>
         <groupid>com.vaticle.typedb</groupid>
         <artifactid>typedb-driver</artifactid>
-        <version>2.28.0-rc0</version>
+        <version>2.28.0</version>
     </dependency>
 </dependencies>
 ```
@@ -42,7 +42,7 @@ Documentation: https://typedb.com/docs/drivers/python/overview
 Available through https://pypi.org
 
 ```
-pip install typedb-driver==2.28.0rc0
+pip install typedb-driver==2.28.0
 ```
 
 ### NodeJS driver
@@ -51,36 +51,41 @@ NPM package: https://www.npmjs.com/package/typedb-driver
 Documentation: https://typedb.com/docs/drivers/nodejs/overview
 
 ```
-npm install [email protected]-rc0
+npm install [email protected]
 ```
 
 ### C# driver
 
-NuGet package: Coming soon
-Documentation: Coming soon
+NuGet package: https://www.nuget.org/packages/TypeDB.Driver
+Documentation: https://typedb.com/docs/drivers/csharp/overview
 
 ```xml
 <ItemGroup>
-    <PackageReference Include="TypeDB.Driver" Version="2.28.0-rc0" />
-    <PackageReference Include="TypeDB.Driver.Pinvoke.osx-x64" Version="2.28.0-rc0" />
-    <PackageReference Include="TypeDB.Driver.Pinvoke.linux-x64" Version="2.28.0-rc0" />
-    <PackageReference Include="TypeDB.Driver.Pinvoke.win-x64" Version="2.28.0-rc0" />
-    <PackageReference Include="TypeDB.Driver.Pinvoke.osx-arm64" Version="2.28.0-rc0" />
-    <PackageReference Include="TypeDB.Driver.Pinvoke.linux-arm64" Version="2.28.0-rc0" />
+    <PackageReference Include="TypeDB.Driver" Version="2.28.0" />
+    <PackageReference Include="TypeDB.Driver.Pinvoke.osx-x64" Version="2.28.0" />
+    <PackageReference Include="TypeDB.Driver.Pinvoke.linux-x64" Version="2.28.0" />
+    <PackageReference Include="TypeDB.Driver.Pinvoke.win-x64" Version="2.28.0" />
+    <PackageReference Include="TypeDB.Driver.Pinvoke.osx-arm64" Version="2.28.0" />
+    <PackageReference Include="TypeDB.Driver.Pinvoke.linux-arm64" Version="2.28.0" />
 </ItemGroup>
 ```
 
 ### C++ driver
 
-Compiled distributions comprising headers and shared libraries available at: https://cloudsmith.io/~typedb/repos/public-release/packages/?q=name:^typedb-driver-cpp+version:2.28.0-rc0
+Compiled distributions comprising headers and shared libraries available at: https://cloudsmith.io/~typedb/repos/public-release/packages/?q=name:^typedb-driver-cpp+version:2.28.0
 Documentation: https://typedb.com/docs/drivers/cpp/overview
 
 ### C driver
 
-Compiled distributions comprising headers and shared libraries available at: https://cloudsmith.io/~typedb/repos/public-release/packages/?q=name:^typedb-driver-clib+version:2.28.0-rc0
+Compiled distributions comprising headers and shared libraries available at: https://cloudsmith.io/~typedb/repos/public-release/packages/?q=name:^typedb-driver-clib+version:2.28.0
 
 
 ## New Features
+- **Implement a method to convert a JSON object to a JSON string**
+
+  The `toString()` method is callable for JSON class objects. It returns a string.
+
+
 - **Address translation**
 
   We allow the user to provide a translation map from the advertised server addresses (now treated as generic server names) to the actual addresses the driver shall use to connect to the cloud instances. We require the user to provide the full mapping.
@@ -218,14 +223,6 @@ Compiled distributions comprising headers and shared libraries available at: htt
 
 
 ## Bugs Fixed
-- **Update Git patch during Windows Circle CI initial job setup**
-
-  We update the Windows Circle CI git patch file to be compatible with the WORKSPACE file which has been recently updated. We also add a check of whether the git patch was successfully applied to catch such mistakes early in the future.
-
-- **Fix deadsnakes ppa in Circle CI sync-dependencies release job**
-
-  Add `-y` to the `add-apt-repository` command in the Circle CI sync-dependencies release job.
-
 
 ## Code Refactors
 - **Implement new steps for getting answers from templated get**
@@ -240,6 +237,33 @@ Compiled distributions comprising headers and shared libraries available at: htt
 
 
 ## Other Improvements
+- **Fixes to C++ structure based on feedback from website**
+  Various improvements to the document generation tools to make the C++ and C driver docs on the website more readable
+
+
+- **Update the README.md for the C driver**
+
+  Update the readme file for the latest filenames.
+
+
+- **Fix C# README examples and add issues refs to recent TODOs**
+  C# driver's examples should be able to be built in any namespace now.
+
+  Some of the recent `TODO`s left in the codebase have been cleaned or marked with a specific GitHub issue number.  
+
+
+- **Python: ABC and typing are not interchangeable**
+
+- **Increase wait time in start-core-server to 10 s, add error message**
+
+- **Increase bootup timeout to 5 seconds in CI tests**
+
+- **Deploy C# driver in a separate job**
+
+  Currently, Bazel generates three different build configurations for the underlying FFI library during C# driver deployment. As that requires compilation of the binding generator and lengthy project analysis, that step is prone to random failures (`socket closed`).
+
+  As the full analysis of the issue proved time-consuming, we instead opt to make the C# driver deployment step easily retriable.
+
 - **Fix parsing & formatting issues for C, C++ documentation**
   Fixes the automatic documentation generation tools for the C & C++ drivers (1) to be  consistent with other languages in terms of structure, and (2) removes stray duplication of parameter documentation in method descriptions.
 
@@ -256,7 +280,3 @@ Compiled distributions comprising headers and shared libraries available at: htt
 
   We add missing documentation for the `setSupertype` concept API in the NodeJS Driver.
 
-- **Merge master to development after 2.27.0 release**
-  We merge back changes made during the release process for 2.27.0, including changes to test infrastructure to explicitly disable monitoring (for port clashes) and diagnostics (to avoid spurious error reports).
-
-

RELEASE_TEMPLATE.md

@@ -56,8 +56,8 @@ npm install typedb-driver@{version}
 
 ### C# driver
 
-NuGet package: Coming soon
-Documentation: Coming soon
+NuGet package: https://www.nuget.org/packages/TypeDB.Driver
+Documentation: https://typedb.com/docs/drivers/csharp/overview
 
 ```xml
 <ItemGroup>

VERSION

@@ -1 +1 @@
-2.28.0-rc0
+2.28.0

c/BUILD

@@ -222,21 +222,21 @@ filegroup(
     output_group = "header"
 )
 
+# TODO: Not hermetic - requires doxygen on the host (https://github.com/vaticle/bazel-distribution/issues/412)
 doxygen_docs(
     name = "docs_html",
     project_name = "TypeDB C Driver",
     sources = [":_typedb_driver_h_only"],
     main_page_md = ":README.md",
     tags = ["manual"],
-
 )
 
 doxygen_c_to_adoc(
     name = "docs_adoc",
     data = [":docs_html"],
     docs_dirs = dir_mapping,
     force_file = force_file,
-    output_dir = "c/docs",
+    output_dir = "docs/modules/ROOT/partials/c",
     tags = ["manual"]
 )
 

c/README.md

@@ -5,24 +5,22 @@ It also serves as the base on which the other wrapper drivers are built.
 ## Usage
 The driver is distributed as an archive containing the headers & a shared library.
 ```
-|- README.md
 |- include/
 |  |- typedb_driver.h
-|  |- ...
 |
 |- lib/
-   |- typedb-driver-clib-<platform>.<ext>
+   |- libtypedb_driver_clib.<ext>
 ```
 
-As usual, Add the include paths to your compile step & the library to your link step. For windows, the 'import-lib' `typedb-driver-cpp-<platform>.if.lib` is provided to link against.
-A [sample `CMakeLists`](https://github.com/vaticle/typedb-driver/blob/master/c/tests/assembly/CMakeLists.txt) is available on the TypeDB Driver repository.
+As usual, add the include paths to your compile step & the library to your link step. For Windows, the 'import-lib' `typedb_driver_clib.dll.lib` is provided to link against.
+A sample [CMakeLists.txt](https://github.com/vaticle/typedb-driver/blob/master/c/tests/assembly/CMakeLists.txt) file is available in the TypeDB Driver repository.
 Code examples can be found in the [integration tests](https://github.com/vaticle/typedb-driver/blob/master/c/tests/integration/driver_test.c). 
 
 ## Architecture
 ### Interface
 `typedb_driver.h` is a single header containing all the functions needed for a complete TypeDB driver.
 
-Functions parameters & return values are either primitives or pointers to opaque `struct`s. e.g.:
+Functions parameters & return values are either primitives or pointers to opaque structs, e.g.:
 ```c
 Connection *connection_open_core(const char *address);
 ``` 

cpp/BUILD

@@ -51,6 +51,7 @@ cc_binary(
     copts = cxxopts,
     linkopts = select({
         "@vaticle_bazel_distribution//platform:is_windows": ["ntdll.lib", "secur32.lib", "crypt32.lib", "ncrypt.lib"],
+        "@vaticle_bazel_distribution//platform:is_mac": ["-framework CoreFoundation"],
         "//conditions:default": [],
     }),
     local_defines = ["_COMPILING_TYPEDB_DRIVER"],
@@ -199,8 +200,7 @@ alias(
     })
 )
 
-# docs
-# TODO: Not hermetic - requires doxygen on the host
+# TODO: Not hermetic - requires doxygen on the host (https://github.com/vaticle/bazel-distribution/issues/412)
 doxygen_docs(
     name = "docs_html",
     project_name = "TypeDB C++ Driver",
@@ -213,7 +213,7 @@ doxygen_cpp_to_adoc(
     name = "docs_adoc",
     data = [":docs_html"],
     docs_dirs = dir_mapping,
-    output_dir = 'cpp/docs',
+    output_dir = 'docs/modules/ROOT/partials/cpp',
     tags = ["manual"]
 )