Add documentation for the upgrade feature #1311

Torch3333 · 2023-11-22T23:15:39Z

Description

Adds documentation for the upgrade feature that was added to the Admin API (admin.upgrade(...)) and Schema Loader (--upgrade command).

Related issues and/or PRs

Changes made

This adds sections for the upgrade feature to the api-guide, api-abstraction and Schema Loader documentations.

Checklist

The following is a best-effort checklist. If any items in this checklist are not applicable to this PR or are dependent on other, unmerged PRs, please still mark the checkboxes after you have read and understood each item.

I have commented my code, particularly in hard-to-understand areas.
I have updated the documentation to reflect the changes.
Any remaining open issues linked to this PR are documented and up-to-date (Jira, GitHub, etc.).
Tests (unit, integration, etc.) have been added for the changes.
My changes generate no new warnings.
Any dependent changes in other PRs have been merged and published.

Additional notes (optional)

N/A

Release notes

N/A

komamitsu

LGTM! 👍

komamitsu · 2023-11-24T02:27:44Z

docs/api-guide.md

@@ -250,6 +250,18 @@ You can get table metadata as follows:
 TableMetadata tableMetadata = admin.getTableMetadata("ns", "tbl");
 ```

+### Upgrade the environment to support the latest ScalarDB API
+
+You can upgrade the ScalarDB environment to support the latest version of the ScalarDB API. Typically,


[trivial] Maybe this is a matter of taste, but

you will be requested

"you will need" is a bit clearer?

I agree; it sounds better. Thanks.

I applied your suggestion and also updated Java files containing documentation for upgrade which use the same wording.
a36972b

brfrn169

LGTM! Thank you!

kota2and3kan

LTGM! Thank you!
I left a very minor comment.
Please take a look when you have time!

docs/schema-loader.md

josh-wong

I've added some suggestions. PTAL!

docs/api-guide.md

josh-wong · 2023-11-29T03:45:18Z

docs/schema-loader.md

+      --upgrade       Upgrades the ScalarDB environment to support the latest
+                        version of the ScalarDB API. Typically, you will be
+                        requested, as indicated on the release notes, to run
+                        this command after updating the ScalarDB version of
+                        your application environment.


Suggested change

--upgrade Upgrades the ScalarDB environment to support the latest

version of the ScalarDB API. Typically, you will be

requested, as indicated on the release notes, to run

this command after updating the ScalarDB version of

your application environment.

--upgrade Upgrades the ScalarDB environment to support the latest

version of the ScalarDB API. Typically, you will need, as indicated in the release notes, to run

this command after updating the ScalarDB version that

your application environment uses.

Thank you. This suggestion is similar to #1311 (comment) so I did not apply it.

I made some changes aside from the word need in my original suggestion. (Sorry, my other changes in my suggestion were a bit hard to see.)

Please see my new comment/suggestion, which also incorporates @feeblefakie's suggestion.

docs/schema-loader.md

docs/storage-abstraction.md

Co-authored-by: Josh Wong <joshua.wong@scalar-labs.com> Co-authored-by: kota2and3kan <47254383+kota2and3kan@users.noreply.github.com>

feeblefakie

Overall, looking good.
I left one suggestion. There are several places that use the same expression, so I also left comments on those. (but I didn't do it for all the places.)

feeblefakie · 2023-11-30T04:12:18Z

core/src/main/java/com/scalar/db/api/Admin.java

@@ -436,7 +436,7 @@ void importTable(String namespace, String table, Map<String, String> options)

  /**
   * Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically,
-   * you will be requested, as indicated on the release notes, to run this method after updating the
+   * you will need, as indicated on the release notes, to run this method after updating the


Suggested change

* you will need, as indicated on the release notes, to run this method after updating the

* as indicated on the release notes, you will need to run this method after updating the

@Torch3333 I didn't see that the wording in some of the non-.md files matched the same wording in the .md files, so I'm making a suggestion here.

My suggestion below (and in my other comments that contain this sentence revises that) addresses @feeblefakie's suggestion and applies other wording that is consistent with my original suggestion.

Suggested change

* you will need, as indicated on the release notes, to run this method after updating the

* as indicated in the release notes, you will need to run this method after updating the

feeblefakie · 2023-11-30T04:12:34Z

docs/api-guide.md

@@ -250,6 +250,16 @@ You can get table metadata as follows:
 TableMetadata tableMetadata = admin.getTableMetadata("ns", "tbl");
 ```

+### Upgrade the environment to support the latest ScalarDB API
+
+You can upgrade the ScalarDB environment to support the latest version of the ScalarDB API. Typically, you will need, as indicated in the release notes, to run this method after updating the ScalarDB version that your application environment uses.


feeblefakie · 2023-11-30T04:12:42Z

docs/schema-loader.md

@@ -92,6 +92,12 @@ Create/Delete schemas in the storage defined in the config file
                      The replication strategy, must be SimpleStrategy or
                        NetworkTopologyStrategy (supported in Cassandra)
      --ru=<ru>       Base resource unit (supported in DynamoDB, Cosmos DB)
+      --upgrade       Upgrades the ScalarDB environment to support the latest
+                        version of the ScalarDB API. Typically, you will
+                        need, as indicated on the release notes, to run


feeblefakie · 2023-11-30T04:13:10Z

docs/schema-loader.md

@@ -439,6 +445,14 @@ $ java -jar scalardb-schema-loader-<VERSION>.jar --jdbc -j <JDBC_URL> -u <USER>

 <div class="notice--info">{{ notice--info | markdownify }}</div>

+### Upgrade the environment to support the latest ScalarDB API
+
+You can upgrade the ScalarDB environment to support the latest version of the ScalarDB API. Typically, you will need, as indicated in the release notes, to run this method after updating the ScalarDB version that your application environment uses.


feeblefakie · 2023-11-30T04:13:18Z

docs/storage-abstraction.md

@@ -405,6 +405,16 @@ You can get table metadata as follows:
 TableMetadata tableMetadata = admin.getTableMetadata("ns", "tbl");
 ```

+### Upgrade the environment to support the latest ScalarDB API
+
+You can upgrade the ScalarDB environment to support the latest version of the ScalarDB API. Typically, you will need, as indicated in the release notes, to run this method after updating the ScalarDB version that your application environment uses.


josh-wong

Made some suggestions mostly in source code files based on a similar sentence in the Markdown files. PTAL!

josh-wong · 2023-11-30T07:59:00Z

core/src/main/java/com/scalar/db/api/Admin.java

@@ -436,7 +436,7 @@ void importTable(String namespace, String table, Map<String, String> options)

  /**
   * Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically,
-   * you will be requested, as indicated on the release notes, to run this method after updating the
+   * you will need, as indicated on the release notes, to run this method after updating the


@Torch3333 I didn't see that the wording in some of the non-.md files matched the same wording in the .md files, so I'm making a suggestion here.

My suggestion below (and in my other comments that contain this sentence revises that) addresses @feeblefakie's suggestion and applies other wording that is consistent with my original suggestion.

Suggested change

* you will need, as indicated on the release notes, to run this method after updating the

* as indicated in the release notes, you will need to run this method after updating the

josh-wong · 2023-11-30T08:07:45Z

docs/schema-loader.md

+      --upgrade       Upgrades the ScalarDB environment to support the latest
+                        version of the ScalarDB API. Typically, you will
+                        need, as indicated on the release notes, to run
+                        this command after updating the ScalarDB version of
+                        your application environment.


I made some changes aside from the word need in my original suggestion. (Sorry, my other changes in my suggestion were a bit hard to see.)

I've also included @feeblefakie's suggestion in my suggestion below:

Suggested change

--upgrade Upgrades the ScalarDB environment to support the latest

version of the ScalarDB API. Typically, you will

need, as indicated on the release notes, to run

this command after updating the ScalarDB version of

your application environment.

--upgrade Upgrades the ScalarDB environment to support the

latest version of the ScalarDB API. Typically, as

indicated in the release notes, you will need to

run this command after updating the ScalarDB

version that your application environment uses.

josh-wong · 2023-11-30T09:07:02Z

core/src/main/java/com/scalar/db/api/Admin.java

@@ -436,7 +436,7 @@ void importTable(String namespace, String table, Map<String, String> options)

  /**
   * Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically,
-   * you will be requested, as indicated on the release notes, to run this method after updating the
+   * you will need, as indicated on the release notes, to run this method after updating the
   * ScalarDB version of your application environment.


Suggested change

* ScalarDB version of your application environment.

* ScalarDB version that your application environment uses.

josh-wong · 2023-11-30T09:16:15Z

schema-loader/src/main/java/com/scalar/db/schemaloader/SchemaLoader.java

+   * you will need, as indicated on the release notes, to run this method after updating the
   * ScalarDB version of your application environment.


Similar to my previous comment.

Suggested change

* you will need, as indicated on the release notes, to run this method after updating the

* ScalarDB version of your application environment.

* as indicated in the release notes, you will need to run this method after updating the

* ScalarDB version that your application environment uses.

josh-wong · 2023-11-30T09:16:38Z

schema-loader/src/main/java/com/scalar/db/schemaloader/SchemaLoader.java

+   * you will need, as indicated on the release notes, to run this method after updating the
   * ScalarDB version of your application environment.


Similar to my previous comment.

Suggested change

* you will need, as indicated on the release notes, to run this method after updating the

* ScalarDB version of your application environment.

* as indicated in the release notes, you will need to run this method after updating the

* ScalarDB version that your application environment uses.

josh-wong · 2023-11-30T09:18:02Z

schema-loader/src/main/java/com/scalar/db/schemaloader/command/SchemaLoaderCommand.java

+            "Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically, you will need, as indicated on the release notes, to run this command after"
                + " updating the ScalarDB version of your application environment.",


Similar to my previous comment.

Suggested change

"Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically, you will need, as indicated on the release notes, to run this command after"

+ " updating the ScalarDB version of your application environment.",

"Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically, as indicated in the release notes, you will need to run this command after"

+ " updating the ScalarDB version that your application environment uses.",

…_for_upgrade # Conflicts: # docs/api-guide.md # docs/schema-loader.md # docs/storage-abstraction.md

Torch3333 · 2023-11-30T10:41:22Z

@feeblefakie @josh-wong
Thank you again. I applied your suggestions. PTAL when you can 🙇

josh-wong

I've left a minor suggestion (an oversight on my part...). Other than that, LGTM! Thank you!

docs/schema-loader.md

Co-authored-by: Josh Wong <joshua.wong@scalar-labs.com>

feeblefakie

LGTM! Thank you!

Add doc for upgrade

37fbae9

Torch3333 changed the title ~~Add documentation for upgrade~~ Add documentation for the upgrade feature Nov 22, 2023

Torch3333 marked this pull request as ready for review November 22, 2023 23:24

Torch3333 self-assigned this Nov 22, 2023

Torch3333 added documentation improvement labels Nov 22, 2023

Torch3333 requested review from komamitsu, brfrn169, feeblefakie and josh-wong November 22, 2023 23:26

komamitsu approved these changes Nov 24, 2023

View reviewed changes

Apply @komamitsu comment

a36972b

brfrn169 approved these changes Nov 29, 2023

View reviewed changes

brfrn169 requested a review from kota2and3kan November 29, 2023 00:41

kota2and3kan approved these changes Nov 29, 2023

View reviewed changes

docs/schema-loader.md Outdated Show resolved Hide resolved

josh-wong requested changes Nov 29, 2023

View reviewed changes

Apply suggestions from code review [skip ci]

3386a43

Co-authored-by: Josh Wong <joshua.wong@scalar-labs.com> Co-authored-by: kota2and3kan <47254383+kota2and3kan@users.noreply.github.com>

Torch3333 requested a review from josh-wong November 29, 2023 21:47

feeblefakie reviewed Nov 30, 2023

View reviewed changes

josh-wong requested changes Nov 30, 2023

View reviewed changes

Torch3333 force-pushed the add_doc_for_upgrade branch from 2a6d219 to f4ebd41 Compare November 30, 2023 10:18

Apply comments [skip ci]

7e5726f

Torch3333 force-pushed the add_doc_for_upgrade branch from f4ebd41 to 7e5726f Compare November 30, 2023 10:23

Merge branch 'master' of github.com:scalar-labs/scalardb into add_doc…

57a3fd1

…_for_upgrade # Conflicts: # docs/api-guide.md # docs/schema-loader.md # docs/storage-abstraction.md

josh-wong approved these changes Nov 30, 2023

View reviewed changes

docs/schema-loader.md Outdated Show resolved Hide resolved

brfrn169 requested a review from feeblefakie December 1, 2023 07:59

Update docs/schema-loader.md

7d6d159

Co-authored-by: Josh Wong <joshua.wong@scalar-labs.com>

feeblefakie approved these changes Dec 5, 2023

View reviewed changes

feeblefakie merged commit 00ae163 into master Dec 5, 2023
23 checks passed

feeblefakie deleted the add_doc_for_upgrade branch December 5, 2023 08:42

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for the upgrade feature #1311

Add documentation for the upgrade feature #1311

Torch3333 commented Nov 22, 2023 •

edited

Loading

komamitsu left a comment

komamitsu Nov 24, 2023

Torch3333 Nov 28, 2023

Torch3333 Nov 28, 2023 •

edited

Loading

brfrn169 left a comment

kota2and3kan left a comment

josh-wong left a comment

josh-wong Nov 29, 2023

Torch3333 Nov 29, 2023

josh-wong Nov 30, 2023 •

edited

Loading

feeblefakie left a comment

feeblefakie Nov 30, 2023

josh-wong Nov 30, 2023

feeblefakie Nov 30, 2023

feeblefakie Nov 30, 2023

feeblefakie Nov 30, 2023

feeblefakie Nov 30, 2023

josh-wong left a comment

josh-wong Nov 30, 2023

josh-wong Nov 30, 2023

josh-wong Nov 30, 2023

josh-wong Nov 30, 2023 •

edited

Loading

josh-wong Nov 30, 2023 •

edited

Loading

josh-wong Nov 30, 2023 •

edited

Loading

Torch3333 commented Nov 30, 2023

josh-wong left a comment

feeblefakie left a comment

	* you will need, as indicated on the release notes, to run this method after updating the
	* as indicated on the release notes, you will need to run this method after updating the

	* you will need, as indicated on the release notes, to run this method after updating the
	* as indicated in the release notes, you will need to run this method after updating the

	* ScalarDB version of your application environment.
	* ScalarDB version that your application environment uses.

		"Upgrades the ScalarDB environment to support the latest version of the ScalarDB API. Typically, you will need, as indicated on the release notes, to run this command after"
		+ " updating the ScalarDB version of your application environment.",

Add documentation for the upgrade feature #1311

Add documentation for the upgrade feature #1311

Conversation

Torch3333 commented Nov 22, 2023 • edited Loading

Description

Related issues and/or PRs

Changes made

Checklist

Additional notes (optional)

Release notes

komamitsu left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Torch3333 Nov 28, 2023 • edited Loading

Choose a reason for hiding this comment

brfrn169 left a comment

Choose a reason for hiding this comment

kota2and3kan left a comment

Choose a reason for hiding this comment

josh-wong left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

josh-wong Nov 30, 2023 • edited Loading

Choose a reason for hiding this comment

feeblefakie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

josh-wong left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

josh-wong Nov 30, 2023 • edited Loading

Choose a reason for hiding this comment

josh-wong Nov 30, 2023 • edited Loading

Choose a reason for hiding this comment

josh-wong Nov 30, 2023 • edited Loading

Choose a reason for hiding this comment

Torch3333 commented Nov 30, 2023

josh-wong left a comment

Choose a reason for hiding this comment

feeblefakie left a comment

Choose a reason for hiding this comment

Torch3333 commented Nov 22, 2023 •

edited

Loading

Torch3333 Nov 28, 2023 •

edited

Loading

josh-wong Nov 30, 2023 •

edited

Loading

josh-wong Nov 30, 2023 •

edited

Loading

josh-wong Nov 30, 2023 •

edited

Loading

josh-wong Nov 30, 2023 •

edited

Loading