Rebase for monorepo migration

.github/pull_request_template.md

@@ -3,7 +3,9 @@
 [PR Reviewing Guidelines](https://github.com/mongodb/docs-golang/blob/master/REVIEWING.md)
 
 JIRA - <https://jira.mongodb.org/browse/DOCSP-NNNNN>
-Staging - <https://docs-mongodbcom-staging.corp.mongodb.com/drivers/docsworker-xlarge/NNNNN/>
+
+### Staging Links
+<!-- start insert-links --><!-- end insert-links -->
 
 ## Self-Review Checklist
 

.github/workflows/add-netlify-links.yml

@@ -0,0 +1,58 @@
+name: Add Netlify Links To Changed Pages
+on:
+  workflow_call:
+  pull_request_target:
+jobs:
+  get-pr-changes:
+    name: Get Changed Files & Update PR Description
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      contents: write
+      pull-requests: write
+      repository-projects: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Get Changed Files
+        id: changed-files
+        # pin to a specific commit to ensure stability
+        uses: tj-actions/changed-files@c65cd883420fd2eb864698a825fc4162dd94482c
+        with:
+          separator: ","
+          files: source/**
+      - name: Build Netlify Links for Changed Pages
+        id: build_page_links
+        env:
+          CHANGED_FILES: ${{ steps.changed-files.outputs.all_changed_files }}
+        run: |
+          new_links=""
+          base_link='https://deploy-preview-${{ github.event.number }}--docs-golang.netlify.app'
+          files=$(echo "$CHANGED_FILES" | tr "," "\n")
+          for file in $files; do
+            echo "processing ${file}"
+            if (! grep -s "includes/"  <<< "$file") && 
+                (! grep -s "images/"  <<< "$file") && 
+                (! grep -s "examples/"  <<< "$file"); then
+              file="${file#source}"
+              file="${file%.txt}"
+              filenoslash="${file:1}"
+              echo "${base_link}${file}"
+              new_links+="<li><a href=${base_link}${file}>${filenoslash}</a></li>"
+            else
+              echo "(file skipped)"
+            fi
+          done
+          if [ "$new_links" == "" ]; then
+            new_links="No pages to preview"
+          fi
+          echo "Final new_links string: "
+          echo "${new_links}"
+          echo "staging_links=${new_links}" >> "$GITHUB_OUTPUT"
+      - name: Update the PR Description
+        uses: MongoCaleb/pr-description-action@master
+        with:
+          regex: "<!-- start insert-links -->.*<!-- end insert-links -->"
+          appendContentOnMatchOnly: true
+          regexFlags: is
+          content: "<!-- start insert-links -->\n${{ steps.build_page_links.outputs.staging_links }}\n<!-- end insert-links -->"
+          token: ${{ secrets.GITHUB_TOKEN }}

config/redirects

@@ -17,3 +17,11 @@ raw: ${prefix}/master -> ${base}/upcoming/
 [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/change-a-document/ -> ${base}/${version}/fundamentals/crud/write-operations/modify/
 [*-master]: ${prefix}/${version}/fundamentals/connection/ -> ${base}/${version}/fundamentals/connections/connection-guide
 [*-master]: ${prefix}/${version}/fundamentals/network-compression/ -> ${base}/${version}/fundamentals/connections/network-compression/
+[*-master]: ${prefix}/${version}/fundamentals/crud/write-read-pref/ -> ${base}/${version}/crud/configure/
+[*-master]: ${prefix}/${version}/fundamentals/collations/ -> ${base}/${version}/crud/configure/
+
+# CC Redirects
+[v1.12-master]: ${prefix}/${version}/usage-examples/struct-tagging/ -> ${base}/${version}/data-formats/struct-tagging/
+[v1.12-master]: ${prefix}/${version}/fundamentals/context/ -> ${base}/${version}/context
+[v1.12-master]: ${prefix}/${version}/usage-examples/changestream -> ${base}/${version}/monitoring-and-logging/change-streams/
+[v1.12-master]: ${prefix}/${version}/fundamentals/crud/read-operations/changestream/ -> ${base}/${version}/monitoring-and-logging/change-streams/

snooty.toml

@@ -1,9 +1,14 @@
 name = "golang"
 title = "Go Driver"
 toc_landing_pages = [
-    "/fundamentals/connections",
-    "/fundamentals/crud",
-    "/usage-examples",
+    "/connect",
+    "/context",
+    "/crud",
+    "/crud/update",
+    "/monitoring-and-logging",
+    "/security",
+    "/security/authentication",
+    "/connect/specify-connection-options",
 ]
 
 intersphinx = [
@@ -17,11 +22,13 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 api-version = "v2"
 driver-long = "MongoDB Go Driver"
 driver-short = "Go driver"
+language = "Go"
 docs-branch = "master"
-version = "v2.1"
-full-version = "{+version+}.0"
+version = "v2.2"
+full-version = "{+version+}.2"
 example = "https://raw.githubusercontent.com/mongodb/docs-golang/{+docs-branch+}/source/includes/usage-examples/code-snippets"
 api = "https://pkg.go.dev/go.mongodb.org/mongo-driver/{+api-version+}"
+min-lang-version = "1.19"
 stable-api = "Stable API"
 qe = "Queryable Encryption"
 key-vault-long = "key vault collection"

source/fundamentals/aggregation.txt → source/aggregation.txt

@@ -25,6 +25,12 @@ pipeline consists of one or more **stages**. Each stage performs an
 operation based on its expression operators. After the driver executes
 the aggregation pipeline, it returns an aggregated result.
 
+.. sharedinclude:: dbx/agg-tutorials-manual-tip.rst
+
+   .. replacement:: language
+
+      :guilabel:`{+language+}`
+
 Analogy
 ~~~~~~~
 

source/archive-reference-files/faq.txt

@@ -0,0 +1,192 @@
+.. _golang-faq:
+
+===
+FAQ
+===
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, connection error, question, help
+   :description: Find answers to common questions about the MongoDB Go Driver, including connection pooling, error handling, and BSON to JSON conversion.
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+This page contains frequently asked questions and their corresponding answers.
+
+.. tip::
+
+   If you can't find an answer to your problem on this page,
+   see the :ref:`golang-issues-and-help` page for next steps and more
+   resources.
+
+Why Am I Getting Errors While Connecting to MongoDB?
+----------------------------------------------------
+
+If you have trouble connecting to a MongoDB deployment, see
+the :ref:`Connection Troubleshooting Guide <golang-connection-troubleshooting>`
+for possible solutions.
+
+.. _golang-faq-connection-pool:
+
+How Does Connection Pooling Work in the {+driver-short+}?
+---------------------------------------------------------
+
+Every ``Client`` instance has a built-in connection pool for each server
+in your MongoDB topology. Connection pools open sockets on demand to support
+concurrent MongoDB operations, or `goroutines
+<https://www.golang-book.com/books/intro/10>`__, in your application.
+
+The maximum size of each connection pool is set by the ``maxPoolSize`` option, which
+defaults to ``100``. If the number of in-use connections to a server reaches
+the value of ``maxPoolSize``, the next request to that server will wait
+until a connection becomes available.
+
+The ``Client`` instance opens two additional sockets per server in your
+MongoDB topology for monitoring the server's state.
+
+For example, a client connected to a 3-node replica set opens 6
+monitoring sockets. It also opens the necessary sockets to support
+an application's concurrent operations on each server, up to
+the value of ``maxPoolSize``. If ``maxPoolSize`` is ``100`` and the
+application only uses the primary (the default), then only the primary
+connection pool grows and there can be at most ``106`` total connections. If the
+application uses a :ref:`read preference <golang-read-pref>` to query the
+secondary nodes, their pools also grow and there can be ``306`` total connections.
+
+Additionally, connection pools are rate-limited such that each connection pool
+can only create, at maximum, the value of ``maxConnecting`` connections
+in parallel at any time. Any additional goroutine stops waiting in the
+following cases:
+
+- One of the existing goroutines finishes creating a connection, or
+  an existing connection is checked back into the pool.
+- The driver's ability to reuse existing connections improves due to
+  rate-limits on connection creation.
+
+You can set the minimum number of concurrent connections to
+each server by using the ``minPoolSize`` option, which defaults to ``0``.
+After setting ``minPoolSize``, the connection pool is initialized with
+this number of sockets. If sockets close due to any network errors, causing
+the total number of sockets (both in use and idle) to drop below the minimum, more sockets
+open until the minimum is reached.
+
+You can set the maximum number of milliseconds that a connection can
+remain idle in the pool before being removed and replaced with
+the ``maxIdleTimeMS`` option, which defaults to ``None`` (no limit).
+
+The following default configuration for a ``Client`` works for most applications:
+
+.. code-block:: go
+
+   client, err := mongo.Connect(options.Client().ApplyURI("<connection string>"))
+
+Create a client once for each process, and reuse it for all
+operations. It is a common mistake to create a new client for each
+request, which is very inefficient.
+
+To support high numbers of concurrent MongoDB operations
+within one process, you can increase ``maxPoolSize``. Once the pool
+reaches its maximum size, additional operations wait for sockets
+to become available.
+
+The driver does not limit the number of operations that
+can wait for sockets to become available and it is the application's
+responsibility to limit the size of its pool to bound queuing
+during a load spike. Operations can wait for any length of time
+unless you define the ``waitQueueTimeoutMS`` option.
+
+An operation that waits more than the length of time defined by
+``waitQueueTimeoutMS`` for a socket raises a connection error. Use this
+option if it is more important to bound the duration of operations
+during a load spike than it is to complete every operation.
+
+When ``Client.Disconnect()`` is called by any goroutine, the driver
+closes all idle sockets and closes all sockets that are in
+use as they are returned to the pool.
+
+How Can I Fix the "WriteNull can only write while positioned on a Element or Value but is positioned on a TopLevel" Error?
+--------------------------------------------------------------------------------------------------------------------------
+
+The ``bson.Marshal()`` method requires a parameter that can be decoded
+into a BSON document, such as the ``bson.D`` type. This error occurs
+when you pass something *other* than a BSON document to
+``bson.Marshal()``.
+
+The ``WriteNull`` error occurs when you pass a ``null`` to
+``bson.Marshal()``. Situations in which a similar error can occur
+include the following:
+
+- You pass a string to ``bson.Marshal()``, causing a ``WriteString`` error.
+- You pass a boolean to ``bson.Marshal()``, causing a ``WriteBoolean`` error.
+- You pass an integer to ``bson.Marshal()``, causing a ``WriteInt32`` error.
+
+You may encounter this error when you perform a CRUD operation that
+internally uses the ``bson.Marshal()`` method or when you call
+``bson.Marshal()`` directly to encode data.
+
+The following code produces a ``WriteNull`` error because the driver
+cannot encode the ``null`` value of ``sortOrder`` to BSON during
+the ``FindOneAndUpdate()`` operation:
+
+.. code-block:: go
+
+   var sortOrder bson.D
+   opts := options.FindOneAndUpdate().SetSort(sortOrder)
+
+   updateDocument := bson.D{{"$inc", bson.D{{"counter", 1}}}}
+   result := coll.FindOneAndUpdate(context.TODO(), bson.D{}, updateDocument, opts)
+   if err := result.Err(); err != nil {
+       panic(err)
+   }
+
+The following code shows how to correctly initialize the ``sortOrder``
+variable as a ``bson.D`` type so that the driver can convert it to BSON:
+
+.. code-block:: go
+
+   sortOrder := bson.D{}
+
+How Do I Convert a BSON Document to JSON?
+-----------------------------------------
+
+The driver provides a variety of marshaler methods that can be used to
+convert a BSON document to JSON, such as the ``MarshalExtJSON()``
+method. To view a readable form of the JSON encoding, you must use
+an unmarshaler method or string type-casting to parse the JSON byte
+format.
+
+The following code converts a BSON document to JSON using the
+``MarshalExtJSON()`` method, then parses and prints the JSON byte array
+using string type-casting:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: go
+      :emphasize-lines: 3
+
+      bsonDocument := bson.D{{"hello", "world"}}
+
+      jsonBytes, err := bson.MarshalExtJSON(bsonDocument, true, false)
+      if err != nil {
+          panic(err)
+      }
+
+      fmt.Println(string(jsonBytes))
+
+   .. output::
+      :language: none
+      :visible: false
+
+      {"hello":"world"}
+
+To learn more about conversions between BSON and Go types, see the
+:ref:`golang-bson` guide.