Update URLs for FerretDB v1 (#4677)

FerretDB · Jan 16, 2025 · a43fcb8 · a43fcb8
1 parent c22b535
commit a43fcb8
Show file tree

Hide file tree

Showing 16 changed files with 126 additions and 124 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml
@@ -17,7 +17,7 @@ body:
       label: FerretDB version
       description: >
         What version and package of FerretDB do you use?
-        Please provide an output of running FerretDB with [`--version` flag](https://docs.ferretdb.io/configuration/flags/).
+        Please provide an output of running FerretDB with [`--version` flag](https://docs.ferretdb.io/v1.24/configuration/flags/).
     validations:
       required: true
   - type: input
@@ -48,7 +48,7 @@ body:
       label: What did you do?
       description: >
         Include MongoDB queries or
-        [pull request with a test script](https://github.com/FerretDB/FerretDB/blob/main/CONTRIBUTING.md#reporting-a-bug)
+        [pull request with a test script](https://github.com/FerretDB/FerretDB/blob/main-v1/CONTRIBUTING.md#reporting-a-bug)
         if you can.
     validations:
       required: true
@@ -65,6 +65,6 @@ body:
     attributes:
       label: What did you see instead?
       description: >
-        Please include FerretDB [logs](https://docs.ferretdb.io/configuration/observability/).
+        Please include FerretDB [logs](https://docs.ferretdb.io/v1.24/configuration/observability/).
     validations:
       required: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -126,7 +126,7 @@ With `task` installed (see above), you may do the following:
 1. Start the development environment with `task env-up`.
 2. Run all tests with `task test` (see [below](#running-tests)).
 3. Start FerretDB with `task run`, `task run-sqlite` or `task run-proxy`.
-   (See [Operation modes](https://docs.ferretdb.io/configuration/operation-modes/) page in our documentation.)
+   (See [Operation modes](https://docs.ferretdb.io/v1.24/configuration/operation-modes/) page in our documentation.)
 4. Fill collections in the `test` database with data for experiments with `task env-data`.
 5. Run `mongosh` with `task mongosh`.
    See what collections were created by the previous command with `show collections`.
@@ -389,4 +389,4 @@ Before submitting a pull request, please make sure that:
    created from the [current state](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
    of our main branch.
 2. Documentation is formatted, linted, and built with `task docs`.
-3. Documentation is written according to our [writing guide](https://docs.ferretdb.io/contributing/writing-guide/).
+3. Documentation is written according to our [writing guide](https://docs.ferretdb.io/v1.24/contributing/writing-guide/).
diff --git a/README.md b/README.md
@@ -3,7 +3,7 @@
 [![Go Reference](https://pkg.go.dev/badge/github.com/FerretDB/FerretDB/ferretdb.svg)](https://pkg.go.dev/github.com/FerretDB/FerretDB/ferretdb)
 
 [![Go](https://github.com/FerretDB/FerretDB/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/FerretDB/FerretDB/actions/workflows/go.yml)
-[![codecov](https://codecov.io/gh/FerretDB/FerretDB/branch/main/graph/badge.svg?token=JZ56XFT3DM)](https://codecov.io/gh/FerretDB/FerretDB)
+[![codecov](https://codecov.io/gh/FerretDB/FerretDB/branch/main-v1/graph/badge.svg?token=JZ56XFT3DM)](https://codecov.io/gh/FerretDB/FerretDB)
 
 [![Security](https://github.com/FerretDB/FerretDB/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/FerretDB/FerretDB/actions/workflows/security.yml)
 [![Packages](https://github.com/FerretDB/FerretDB/actions/workflows/packages.yml/badge.svg?branch=main)](https://github.com/FerretDB/FerretDB/actions/workflows/packages.yml)
@@ -45,7 +45,7 @@ Features are constantly being added to further increase compatibility and perfor
 
 We welcome all contributors.
 See our [public roadmap](https://github.com/orgs/FerretDB/projects/2/views/1),
-a list of [known differences with MongoDB](https://docs.ferretdb.io/diff/),
+a list of [known differences with MongoDB](https://docs.ferretdb.io/v1.24/diff/),
 and [contributing guidelines](CONTRIBUTING.md).
 
 ## Quickstart
@@ -64,7 +64,7 @@ docker run -d --rm --name ferretdb -p 27017:27017 -e FERRETDB_HANDLER=sqlite ghc
 
 This command will start a container with FerretDB, PostgreSQL/SQLite, and MongoDB Shell for quick testing and experiments.
 However, it is unsuitable for production use cases because it keeps all data inside and loses it on shutdown.
-See our [Docker quickstart guide](https://docs.ferretdb.io/quickstart-guide/docker/) for instructions
+See our [Docker quickstart guide](https://docs.ferretdb.io/v1.24/quickstart-guide/docker/) for instructions
 that don't have those problems.
 
 With that container running, you can:
@@ -86,7 +86,7 @@ You can stop the container with `docker stop ferretdb`.
 
 We also provide binaries and packages for various Linux distributions,
 as well as [Go library package](https://pkg.go.dev/github.com/FerretDB/FerretDB/ferretdb) that embeds FerretDB into your application.
-See [our documentation](https://docs.ferretdb.io/quickstart-guide/) for more details.
+See [our documentation](https://docs.ferretdb.io/v1.24/quickstart-guide/) for more details.
 
 ## Building and packaging
 

diff --git a/build/ferretdb.service b/build/ferretdb.service
@@ -9,7 +9,7 @@ ExecStart=/usr/bin/ferretdb
 Restart=on-failure
 
 # Configure the FerretDB service with `systemctl edit ferretdb`.
-# For more configuration options check https://docs.ferretdb.io/configuration/flags/
+# For more configuration options check https://docs.ferretdb.io/v1.24/configuration/flags/
 
 Environment="FERRETDB_POSTGRESQL_URL=postgres://127.0.0.1:5432/ferretdb"
 

diff --git a/internal/handler/msg_saslstart.go b/internal/handler/msg_saslstart.go
@@ -83,7 +83,7 @@ func (h *Handler) saslStart(ctx context.Context, dbName string, document *types.
 			)), nil
 		default:
 			msg := fmt.Sprintf("Unsupported authentication mechanism %q.\n", mechanism) +
-				"See https://docs.ferretdb.io/security/authentication/ for more details."
+				"See https://docs.ferretdb.io/v1.24/security/authentication/ for more details."
 			return nil, handlererrors.NewCommandErrorMsgWithArgument(handlererrors.ErrAuthenticationFailed, msg, "mechanism")
 		}
 	}
@@ -103,7 +103,7 @@ func (h *Handler) saslStart(ctx context.Context, dbName string, document *types.
 		)), nil
 	default:
 		msg := fmt.Sprintf("Unsupported authentication mechanism %q.\n", mechanism) +
-			"See https://docs.ferretdb.io/security/authentication/ for more details."
+			"See https://docs.ferretdb.io/v1.24/security/authentication/ for more details."
 		return nil, handlererrors.NewCommandErrorMsgWithArgument(handlererrors.ErrAuthenticationFailed, msg, "mechanism")
 	}
 }

diff --git a/tools/github/client.go b/tools/github/client.go
@@ -210,7 +210,7 @@ func (c *Client) IssueStatus(ctx context.Context, url string) (IssueStatus, erro
 				msg := "Rate limit reached: " + err.Error()
 				if c.token == "" {
 					msg += "\nPlease set a GITHUB_TOKEN as described at " +
-						"https://github.com/FerretDB/FerretDB/blob/main/CONTRIBUTING.md#setting-a-github_token"
+						"https://github.com/FerretDB/FerretDB/blob/main-v1/CONTRIBUTING.md#setting-a-github_token"
 				}
 				c.logf("%s", msg)
 			}

diff --git a/website/docs/contributing/how-to-contribute.md b/website/docs/contributing/how-to-contribute.md
@@ -25,11 +25,11 @@ We appreciate your feedback.
 ## Contributing to this documentation
 
 If you find anything confusing or missing in the documentation, click the "Edit this page" link at the bottom of almost every page in the documentation.
-More information on contributing to the documentation can be found [here](https://github.com/FerretDB/FerretDB/blob/main/CONTRIBUTING.md#contributing-documentation).
+More information on contributing to the documentation can be found [here](https://github.com/FerretDB/FerretDB/blob/main-v1/CONTRIBUTING.md#contributing-documentation).
 
 ## Contributing to the FerretDB repository
 
-- To contribute to this [FerretDB project](https://github.com/FerretDB/FerretDB/), please read the [CONTRIBUTING.md](https://github.com/FerretDB/FerretDB/blob/main/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](https://github.com/FerretDB/FerretDB/blob/main/CODE_OF_CONDUCT.md) guideline to know more.
+- To contribute to this [FerretDB project](https://github.com/FerretDB/FerretDB/), please read the [CONTRIBUTING.md](https://github.com/FerretDB/FerretDB/blob/main-v1/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](https://github.com/FerretDB/FerretDB/blob/main-v1/CODE_OF_CONDUCT.md) guideline to know more.
 - Is everything working as it should?
   If not, please let us know by [creating an issue](https://github.com/FerretDB/FerretDB/issues/new/choose).
   You can create issues for bugs, documentation, features, or enhancements.

diff --git a/website/docs/diff.md b/website/docs/diff.md
@@ -6,7 +6,7 @@ slug: /diff/ # referenced in README.md
 # Known differences
 
 <!--
-   Each numbered point should have a corresponding, numbered test file https://github.com/FerretDB/FerretDB/tree/main/integration/diff_*_test.go
+   Each numbered point should have a corresponding, numbered test file https://github.com/FerretDB/FerretDB/tree/main-v1/integration/diff_*_test.go
    Bullet subpoints should be in the same file as the parent point.
 -->
 

diff --git a/website/docs/main.md b/website/docs/main.md
@@ -27,7 +27,7 @@ We are constantly adding features to increase compatibility based on user feedba
 
 See our [public roadmap](https://github.com/orgs/FerretDB/projects/2/views/1),
 a list of [known differences with MongoDB](diff.md),
-and [contributing guidelines](https://github.com/FerretDB/FerretDB/blob/main/CONTRIBUTING.md).
+and [contributing guidelines](https://github.com/FerretDB/FerretDB/blob/main-v1/CONTRIBUTING.md).
 
 ## Community
 

diff --git a/website/docs/telemetry.md b/website/docs/telemetry.md
@@ -5,46 +5,47 @@ slug: /telemetry/ # referenced in many places; must not change
 
 # Telemetry reporting
 
-FerretDB collects basic anonymous usage data and sends them to our telemetry service ([FerretDB Beacon](https://beacon.ferretdb.com)),
-which helps us understand its usage, and how we can further increase compatibility and enhance our product.
-It also enables us to provide you information about available updates.
+FerretDB collects basic anonymous usage data and sends it to our telemetry service ([FerretDB Beacon](https://beacon.ferretdb.com)).
+It helps us understand FerretDB usage and how to increase compatibility and enhance our product further.
+It also enables us to provide you with information about available updates.
 
-Your privacy is important to us, and we understand how sensitive data collection can be,
-which is why we are not collecting any personally-identifying information
-or share any of the data with third parties.
+Your privacy is important to us, and we understand how sensitive data collection can be.
+We assure you that we are not collecting any personally identifying information.
+We will never share or sell raw telemetry data to third parties.
+We may share our findings and statistics based on telemetry data with third parties and the general public.
 
 The following data is collected:
 
-- FerretDB version
-- Random instance UUID
+- Random FerretDB instance UUID
 - [Autonomous system](<https://en.wikipedia.org/wiki/Autonomous_system_(Internet)>) number,
-  cloud provider region, or country derived from IP address (but not the IP address itself)
-- Uptime
+  cloud provider region and country derived from the IP address (but not the IP address itself)
+- FerretDB version
 - Backend (PostgreSQL or SQLite) version
 - Installation type (Docker, package, cloud provider marketplace, self-built)
 - Build configuration (Go version, build flags and tags)
+- Uptime
 - Command statistics:
   - protocol operation codes (e.g. `OP_MSG`, `OP_QUERY`);
-  - command names (e.g. `find`, `aggregate`);
-  - arguments (e.g. `sort`, `$count (stage)`);
-  - error codes (e.g. `NotImplemented`, `InternalError`; or `ok`).
+  - command names (e.g., `find`, `aggregate`);
+  - arguments (e.g., `sort`, `$count`);
+  - error codes (e.g., `NotImplemented`, `InternalError`; or `ok`).
 
 :::info
 Argument values, data field names, successful responses, or error messages are never collected.
 :::
 
-## Version notification
+## Version notifications
 
 When a FerretDB update is available,
-the telemetry service sends periodic notifications containing information about the latest FerretDB version.
-This information is logged in the server logs and `startupWarnings` command output.
+the telemetry service responds with information about the latest FerretDB version.
+This information is logged in server logs and available via the `getLog` command with the `startupWarnings` argument, making it visible when connecting with various tools such as `mongosh`.
 
 While you may not upgrade to the latest release immediately,
-ensure that you update early to take advantage of recent bug fixes, new features, and performance improvements.
+ensure you update early to take advantage of recent bug fixes, new features, and performance improvements.
 
-## Configure telemetry
+## Configuration
 
-The telemetry reporter has three state settings: `enabled`, `disabled`, and `undecided` (default).
+The telemetry reporter has three state settings: `enabled`, `disabled`, and `undecided` (the default).
 The latter acts as if it is `enabled` with two differences:
 
 - When `enabled`, the first report is sent right after FerretDB starts.
@@ -54,20 +55,16 @@ The latter acts as if it is `enabled` with two differences:
   That does not happen when `undecided`.
 
 :::info
-`undecided` state does not automatically change into `enabled` or `disabled` after the first or any other report.
+`undecided` state does not automatically change into `enabled` or `disabled`.
 Explicit user action is required (see below) to change an `undecided` state to `enabled` or `disabled`.
 :::
 
 Telemetry reporting is always disabled for [embedded FerretDB](https://pkg.go.dev/github.com/FerretDB/FerretDB/ferretdb)
 and can't be configured.
 
-:::info
-Despite the autogenerated message by `mongosh` regarding MongoDB's free cloud-based monitoring service, please note that no data will ever be shared with MongoDB Inc.
-:::
-
 ### Disable telemetry
 
-We urge you not to disable telemetry reporter, as its insights will help us enhance our software.
+We urge you not to disable the telemetry reporter, as its insights will help us enhance our software.
 
 While we are grateful for these usage insights, we understand that not everyone is comfortable with sending them.
 
@@ -84,7 +81,7 @@ Telemetry can be disabled using any of the following options:
    --telemetry=disable
    ```
 
-2. Set the environment variable `FERRETDB_TELEMETRY`.
+2. Set the environment variable `FERRETDB_TELEMETRY` with the same value as above:
 
    ```sh
    export FERRETDB_TELEMETRY=disable
@@ -97,11 +94,11 @@ Telemetry can be disabled using any of the following options:
    export DO_NOT_TRACK=true
    ```
 
-4. Rename FerretDB executable to include a `donottrack` string.
+4. Rename the FerretDB executable to include a `donottrack` string.
 
    :::caution
    If telemetry is disabled using this option, you cannot use the `--telemetry` flag or environment variables
-   until the `donottrack` string is removed.
+   until the `donottrack` string is removed from the executable.
    :::
 
 5. Use the `db.disableFreeMonitoring()` command on runtime.
@@ -111,21 +108,21 @@ Telemetry can be disabled using any of the following options:
    ```
 
    :::caution
-   If the telemetry is set via a command-line flag, an environment variable or a filename, it's not possible
+   If the telemetry is set via a command-line flag, an environment variable, or a filename, it's not possible
    to modify its state via command.
    :::
 
 ### Enable telemetry
 
-Telemetry can be explicitly enabled (see [above](#configure-telemetry)) with the command-line flag `--telemetry`
+Telemetry can be explicitly enabled (see [above](#configuration)) with the command-line flag `--telemetry`
 by setting one of the values:
 `1`, `t`, `true`, `y`, `yes`, `on`, `enable`, `enabled`, `optin`, `opt-in`, `allow`.
 
 ```sh
 --telemetry=enable
 ```
 
-You can also use `FERRETDB_TELEMETRY` environment variable with same values
+You can also use `FERRETDB_TELEMETRY` environment variable with the same values as above
 or on runtime via `db.enableFreeMonitoring()` command.
 
 ```sh
@@ -137,15 +134,15 @@ db.enableFreeMonitoring()
 ```
 
 One case when explicitly enabling telemetry is useful is if you want to help us improve compatibility
-with your application by running its integration tests or just by testing it manually.
+with your application by running its integration tests or manually testing it.
 If you leave the telemetry state undecided and your test lasts less than an hour,
 we will not have data about unimplemented commands and errors.
 
 If you want to help us with that, please do the following:
 
 1. Start FerretDB with [debug logging](configuration/flags.md) and telemetry explicitly enabled.
    Confirm that telemetry is enabled from the logs.
-2. Test your application with integration tests or manually.
+2. Test your application manually or with integration tests.
 3. Gracefully stop FerretDB with `SIGTERM` or `docker stop` (not with `SIGKILL` or `docker kill`).
 4. Optionally, locate instance UUID in the `state.json` file in the state directory
    (`/state` for Docker, current directory otherwise) and send it to us.