WRITING-26459 Add v2 Migration Guide #1766

prestonvasquez · 2024-08-22T22:25:05Z

WRITING-26459

Summary

Add the v2 migration guide to docs

Background & Motivation

docs/migration-2.0.md

Co-authored-by: Qingyang Hu <[email protected]>

docs/migration-2.0.md

Co-authored-by: Julia Tazin <[email protected]>

jtazin

A few formatting suggestions

docs/migration-2.0.md

jtazin · 2024-08-23T17:08:50Z

docs/migration-2.0.md

+- `UnmarshalExtJSONWithRegistry`
+- `UnmarshalExtJSONWithContext`
+
+For example, a boolean type can be stored in the database as a BSON boolean, int32, or int64. Given a registry:


Suggested change

For example, a boolean type can be stored in the database as a BSON boolean, int32, or int64. Given a registry:

For example, a boolean type can be stored in the database as a BSON `Boolean`, `Int32`, or `Int64`. Given a registry:

Go native types are not capitalized.

I regard "boolean", "in32", "int64", or "true" are general concepts, that don't need to be denoted.

@prestonvasquez isn't this specifically talking about the BSON types rather than the native types? This suggestion was based on the code sample below which has bsontype.Boolean, bsontype.Int32, and bsontype.Int64

BSON type references should also not be capitalized.

I think we should either leave them as-is or reference the package type, as you suggest (i.e. bsontype.Boolean).

Ok, I'll defer to your judgement here. I noticed that it was capitalized in the code sample, which is why I suggested it, but if it doesn't make sense, let's keep it as-is. Feel free to resolve this one :)

I've updated the guide to use phrasing from the BSON specifications.

jtazin · 2024-08-23T17:11:49Z

docs/migration-2.0.md

+	bsoncodec.ValueDecoderFunc(lenientBoolDecoder))
+```
+
+For our custom decoder with such a registry, BSON int32 or int64 values are considered "true" if they are non-zero.


Suggested change

For our custom decoder with such a registry, BSON int32 or int64 values are considered "true" if they are non-zero.

For our custom decoder with such a registry, BSON `Int32` or `Int64` values are considered `true` if they are non-zero.

We can keep the int32 and int64 lowercase as discussed in the previous thread.
But I'm guessing we should remove the quotation around "true" though. It's probably best to format it as code (based off of the convention I'm noticing in the rest of the doc when it comes to values, for example "to differentiate between an ID of 0 and no ID").

docs/migration-2.0.md

jtazin · 2024-08-23T17:14:39Z

docs/migration-2.0.md

+
+### ValueMarshaler
+
+The `MarshalBSONValue` method of the `ValueMarshaler` interface is only required to return a byte type value representing the BSON type to avoid importing the Go driver package.


What's the name of the package that no longer needs to be imported?

@qingyang-hu?

I've updated at 60af8e3

Co-authored-by: Julia Tazin <[email protected]>

docs/migration-2.0.md

Co-authored-by: Julia Tazin <[email protected]>

Co-authored-by: Qingyang Hu <[email protected]>

README.md

docs/migration-2.0.md

Co-authored-by: Rea Rustagi <[email protected]>

rustagir

looks good, I still suggest standardizing the way different code components (methods/types/etc) are displayed, but it is a low priority and users should understand

rustagir · 2024-08-29T14:19:11Z

docs/migration-2.0.md

+```go
+client, err := mongo.NewClient(options.Client())
+if err != nil {
+  log.Fatalf("failed to create client: %v", err)
+}
+
+if err := client.Connect(context.TODO()); err != nil {
+  log.Fatalf("failed to connect to server: %v", err)
+}
+```
+
+```go
+client, err := mongo.Connect(options.Client())
+if err != nil {
+  log.Fatalf("failed to connect to server: %v", err)
+}
+```


S: add the v1 and v2 code comments for clarity

jtazin · 2024-08-30T14:34:06Z

looks good, I still suggest standardizing the way different code components (methods/types/etc) are displayed, but it is a low priority and users should understand

@rustagir agreed, do you have any specific suggestions on how to do that?

rustagir · 2024-09-03T13:12:26Z

Re: #1766 (comment)

In the docs we usually follow the convention to identify code components eg.

You can use the x() method to ...
Pass an instance of y to the z() method to...
The w interface provides...

And so on. But I am leaving this as an optional formatting suggestion for the team.

mongodb-drivers-pr-bot · 2024-09-04T15:26:48Z

API Change Report

No changes found!

WRITING-26459 Add v2 migration guide to docs

8d1c1ae

prestonvasquez changed the base branch from v1 to master August 22, 2024 22:25

mongodb-drivers-pr-bot bot requested a review from qingyang-hu August 22, 2024 22:29

WRITING-26459 Fix indentation

6490707

prestonvasquez requested a review from jtazin August 22, 2024 22:45

WRITING-26459 Update report card link

36761c2

qingyang-hu reviewed Aug 23, 2024

View reviewed changes

docs/migration-2.0.md Outdated Show resolved Hide resolved

qingyang-hu reviewed Aug 23, 2024

View reviewed changes

docs/migration-2.0.md Show resolved Hide resolved

qingyang-hu reviewed Aug 23, 2024

View reviewed changes

docs/migration-2.0.md Outdated Show resolved Hide resolved

qingyang-hu and others added 5 commits August 23, 2024 11:22

WRITING-26568 Add v2 BSON migration guide to docs

abab476

Update docs/migration-2.0.md

cf13f23

Co-authored-by: Qingyang Hu <[email protected]>

Update docs/migration-2.0.md

955d1b0

Co-authored-by: Qingyang Hu <[email protected]>

WRITING-26459 Finish code block

f6db5cd

WRITING-26459 Finish code block

28a27c9

prestonvasquez requested a review from qingyang-hu August 23, 2024 16:04

jtazin requested a review from rustagir August 23, 2024 16:38

jtazin reviewed Aug 23, 2024

View reviewed changes

docs/migration-2.0.md Outdated Show resolved Hide resolved

Update docs/migration-2.0.md

ada1163

Co-authored-by: Julia Tazin <[email protected]>

jtazin reviewed Aug 23, 2024

View reviewed changes

qingyang-hu and others added 6 commits August 23, 2024 13:18

Update docs/migration-2.0.md

a95e576

Co-authored-by: Julia Tazin <[email protected]>

Update v2 migration guide BSON portion

60af8e3

Update docs/migration-2.0.md

9c79933

Co-authored-by: Julia Tazin <[email protected]>

Update docs/migration-2.0.md

500270d

Co-authored-by: Julia Tazin <[email protected]>

Update docs/migration-2.0.md

eb681bb

Co-authored-by: Julia Tazin <[email protected]>

Update docs/migration-2.0.md

b175387

Co-authored-by: Julia Tazin <[email protected]>

qingyang-hu reviewed Aug 23, 2024

View reviewed changes

docs/migration-2.0.md Outdated Show resolved Hide resolved

Update docs/migration-2.0.md

becf0e5

Co-authored-by: Julia Tazin <[email protected]>

prestonvasquez requested review from blink1073 and jtazin August 23, 2024 20:30

mongodb-drivers-pr-bot bot added the documentation Pull requests that update documentation or examples label Aug 23, 2024

mongodb-drivers-pr-bot bot added the review-priority-low Low Priority PR for Review: within 3 business days label Aug 23, 2024

prestonvasquez and others added 2 commits August 26, 2024 09:06

Update docs/migration-2.0.md

54afb21

Co-authored-by: Qingyang Hu <[email protected]>

WRITING-26459 Use BSON documentation nomenclature when referencing types

8ea4956

prestonvasquez requested a review from qingyang-hu August 27, 2024 15:12

qingyang-hu previously approved these changes Aug 27, 2024

View reviewed changes

WRITING-25459 Add punctuation back to guide

9745398

prestonvasquez dismissed qingyang-hu’s stale review via 9745398 August 27, 2024 15:16

WRITING-25459 Update true to use code-form

400c152

rustagir reviewed Aug 27, 2024

View reviewed changes

prestonvasquez and others added 7 commits August 28, 2024 09:55

Update README.md

13303ce

Co-authored-by: Rea Rustagi <[email protected]>

Update docs/migration-2.0.md

fb1e235

Co-authored-by: Rea Rustagi <[email protected]>

Update docs/migration-2.0.md

2307561

Co-authored-by: Rea Rustagi <[email protected]>

Update docs/migration-2.0.md

ec89bef

Co-authored-by: Rea Rustagi <[email protected]>

Update docs/migration-2.0.md

ec0fde5

Co-authored-by: Rea Rustagi <[email protected]>

Update docs/migration-2.0.md

625e4be

Co-authored-by: Rea Rustagi <[email protected]>

Merge branch 'master' into WRITING-26459

78b3b26

prestonvasquez requested review from qingyang-hu and rustagir August 28, 2024 16:02

jtazin approved these changes Aug 28, 2024

View reviewed changes

rustagir approved these changes Aug 29, 2024

View reviewed changes

blink1073 added review-priority-normal Medium Priority PR for Review: within 1 business day and removed review-priority-low Low Priority PR for Review: within 3 business days labels Aug 29, 2024

qingyang-hu approved these changes Sep 4, 2024

View reviewed changes

Merge branch 'master' into WRITING-26459

4eea8a1

Merge branch 'master' into WRITING-26459

a3b56e6

prestonvasquez merged commit 75e02b2 into mongodb:master Sep 4, 2024
3 of 5 checks passed

prestonvasquez deleted the WRITING-26459 branch September 4, 2024 15:44

	For example, a boolean type can be stored in the database as a BSON boolean, int32, or int64. Given a registry:
	For example, a boolean type can be stored in the database as a BSON `Boolean`, `Int32`, or `Int64`. Given a registry:

	For our custom decoder with such a registry, BSON int32 or int64 values are considered "true" if they are non-zero.
	For our custom decoder with such a registry, BSON `Int32` or `Int64` values are considered `true` if they are non-zero.


		### ValueMarshaler

		The `MarshalBSONValue` method of the `ValueMarshaler` interface is only required to return a byte type value representing the BSON type to avoid importing the Go driver package.

WRITING-26459 Add v2 Migration Guide #1766

WRITING-26459 Add v2 Migration Guide #1766

Uh oh!

Conversation

prestonvasquez commented Aug 22, 2024

Summary

Background & Motivation

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jtazin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jtazin commented Aug 30, 2024

Uh oh!

rustagir commented Sep 3, 2024

Uh oh!

mongodb-drivers-pr-bot bot commented Sep 4, 2024

API Change Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants