Details
-
Technical task
-
Resolution: Fixed
-
Major
-
None
-
None
-
None
-
None
-
0
Description
WHICH REPO/BRANCH
git clone git@github.com:couchbase/docs-couchbase-lite.git |
git checkout DOC-10385-Docs-for-Mobile-Scopes-and-Collections |
git pull # update
|
git checkout -b DOC-10388-querybuilder-scopes-and-collections |
WHAT DOCUMENT
We'll start with just C#.net again, and make abstract in a subsequent step.
This is https://docs.couchbase.com/couchbase-lite/current/csharp/querybuilder.html
Because this is an existing doc, it's more complicated to work with.
- START OFF by opening this doc in your Web Browser, and reading through it, alongside the WHAT TO DO section below.
- Figure out what you want to change...
- (we'll then figure out where below)
WHAT TO DO
Requirements:
- author or link to an explanation of how the FROM field has changed.
- e.g. in Example 1. Query Format, it says FROM 'database' but Scopes and Collections changes this.
- Prior art: In the Server docs, https://docs.couchbase.com/server/current/n1ql/n1ql-intro/queriesandresults.html has some useful wording around keypath and "Query Context"
- Anywhere that "Database" is mentioned on this page, we want to change it to "Collection" or possibly keypath/query context.
- This means a lot of the code samples will have to be updated.
- Look at e.g. Example 2. Here, I'm not sure if Indexes are created on Database or Collection.
- We're not experts in the programming, so here, simply CALL OUT the example (see below) for now.
- (If you are curious, you CAN check e.g. in the API Spec https://docs.google.com/document/d/1JsGh5SB0MJ8oeb0kDmFzz9r7K-YUBapz_Dx1XEwiNKU/edit or ask the engineering team, but don't if you feel this is a bad use of your time)
- Look at e.g. Example 3. I think all uses of .From(DataSource.Database(db)) will need rewriting, so signal all these.
- ... and so on
- JOIN examples will probably need update.
Nice-to-haves:
- remove callouts `<.>` by adding introductory text, reorganizing, and/or adding comments to the source code. For some things like "Example 1. Query Format"
WHERE (WHAT FILES TO UPDATE)
Start at the top, and notice how each file include::'s others.
I'll list the ones I think might be most important, and happy to help chase down include chains if it's important.
- modules/csharp/pages/querybuilder.adoc (ENTRYPOINT, but very abstract)
- modules/ROOT/pages/_partials/commons/common-querybuilder.adoc
- modules/csharp/examples/code_snippets/Program.cs
Updating a Code Example
NB: you shouldn't need to do this! See linked tickets for code samples.
Let's say you wanted to update "Example 2. Creating a New Index".
You've looked in common-querybuilder.adoc and all you can find is
[#ex-indexing]
|
.Creating a New Index
|
:param-tags: query-index
|
:param-leader: This example creates a new index for the `type` and `name` properties in the <<ex-data-format>>. |
include::{root-partials}block_tabbed_code_example.adoc[]
|
:param-tags!:
|
:param-leader!:
|
This is super abstract and I'd like to burn it with fire. But suggest we stick with it now for existing pages until we understand the best refactoring step better.
Key info:
- the tag is query-index
- By following the include chain through block_tabbed_code_example.adoc and include::partial$_set_page_context_for_csharp.adoc[] (which was set by the file marked "ENTRYPOINT" above) I chased this down to:
- modules/csharp/examples/code_snippets/Program.cs
- Open this file, and search for //tag::query-index[]
- Check that this is the example you were looking for.
Remember:
- YOU don't need to update any code examples
- I can do best-endeavours on C# if required
ONE LAST DETAIL
Notice that common-querybuilder.adoc has a section marked with "ifdef::is-ios[]".
This means that it's only shown for Apple iOS platform (e.g. Objective C and Swift).
I think we can ignore that here, but you may want to search for "ifdef" and "ifndef" (e.g. if it isn't this platform) in subsequent files you update. I'll triage this for you ongoing.