Reformat and lint more documentation files (FerretDB#2740)

Closes FerretDB#2738.
chilagrow · May 30, 2023 · e4b2185 · e4b2185
1 parent f988145
commit e4b2185
Show file tree

Hide file tree

Showing 42 changed files with 501 additions and 467 deletions.
diff --git a/.codecov.yml → .github/codecov.yml b/.codecov.yml → .github/codecov.yml
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/Taskfile.yml b/Taskfile.yml
@@ -606,8 +606,8 @@ tasks:
     cmds:
       - bin/checkdocs
       - docker compose run --rm textlint --fix --config build/.textlintrc "**/*.md" ".github/**/*.md"
-      - docker compose run --rm prettier --write --parser markdown --no-semi --single-quote --trailing-comma none --ignore-path build/.prettierignore "**/*.md"
-      - docker compose run --rm markdownlint "**/*.md" "#CHANGELOG.md"
+      - docker compose run --rm prettier --write --parser markdown --no-semi --single-quote --trailing-comma none "**/*.md"
+      - docker compose run --rm markdownlint "build/.markdownlint.yml" "**/*.md"
 
   docs-dev:
     desc: "Start documentation development server"

diff --git a/.markdownlint.yml → build/.markdownlint.yml b/.markdownlint.yml → build/.markdownlint.yml
diff --git a/build/.prettierignore b/build/.prettierignore
diff --git a/build/.textlintrc b/build/.textlintrc
@@ -2,6 +2,22 @@
     "rules": {
         "@0x6b/normalize-whitespaces": true,
         "no-zero-width-spaces": true,
-        "one-sentence-per-line": true
+        "one-sentence-per-line": true,
+        "@textlint-rule/pattern": {
+            "patterns": [
+                {
+                    "message": "Use straight ASCII double quotes instead of curly double quotes",
+                    "pattern": "/(“|”)/",
+                    "replace": "\"",
+                    "forceCode": true
+                },
+                {
+                    "message": "Use straight ASCII single quotes instead of curly single quotes",
+                    "pattern": "/(‘|’)/",
+                    "replace": "'",
+                    "forceCode": true
+                }
+            ]
+        }
     }
 }
diff --git a/build/deps/ferretdb-textlint.Dockerfile b/build/deps/ferretdb-textlint.Dockerfile
@@ -1 +1 @@
-FROM ghcr.io/ferretdb/ferretdb-textlint:13.3.2-3
+FROM ghcr.io/ferretdb/ferretdb-textlint:13.3.2-4
diff --git a/build/deps/markdownlint.Dockerfile b/build/deps/markdownlint.Dockerfile
@@ -1 +1,3 @@
 FROM davidanson/markdownlint-cli2:v0.7.1
+
+ENTRYPOINT [ "markdownlint-cli2-config" ]
diff --git a/internal/handlers/common/update_params.go b/internal/handlers/common/update_params.go
@@ -41,7 +41,7 @@ type UpdateParams struct {
 	// TODO: https://github.com/FerretDB/FerretDB/issues/2627
 	// get comment from query, e.g. db.collection.UpdateOne({"_id":"string", "$comment: "test"},{$set:{"v":"foo""}})
 	Filter *types.Document `ferretdb:"q,opt"`
-	Update *types.Document `ferretdb:"u,opt"`
+	Update *types.Document `ferretdb:"u,opt"` // TODO https://github.com/FerretDB/FerretDB/issues/2742
 	Multi  bool            `ferretdb:"multi,opt"`
 	Upsert bool            `ferretdb:"upsert,opt,numericBool"`
 

diff --git a/website/blog/2021-12-07-mongodb-compatibility-whats-really-important.md b/website/blog/2021-12-07-mongodb-compatibility-whats-really-important.md
@@ -13,7 +13,7 @@ In this recent [TheRegister Article](https://www.theregister.com/2021/12/06/aws_
 
 <!--truncate-->
 
-In the interview, Mark claims that Amazon’s DocumentDB - one of the leading MongoDB alternatives - is just 34% compatible with MongoDB itself.
+In the interview, Mark claims that Amazon's DocumentDB - one of the leading MongoDB alternatives - is just 34% compatible with MongoDB itself.
 
 This looks damning, until you remember the 80/20 rule, which applies here as "80% of applications require just 20% of functionality".
 And if one thing you can count on from AWS is that they are listening to their customers and [choosing functionality](https://docs.aws.amazon.com/documentdb/latest/developerguide/release-notes.html) to implement wisely.
@@ -27,7 +27,7 @@ They just provided the right features to be a great fit for certain applications
 We expect that this is how the MongoDB Alternatives Market will evolve - [DocumentDB](https://aws.amazon.com/documentdb/), [CosmosDB](https://docs.microsoft.com/en-us/azure/cosmos-db/mongodb/mongodb-introduction), [Oracle](https://blogs.oracle.com/database/post/introducing-oracle-database-api-for-mongodb), FerretDB (ourselves) will focus on implementing features which actually matter, not merely trying to achieve some higher compatibility number on arbitrary MongoDB test suites.
 Chances are, the companies will come together to standardize and implement useful extensions to MongoDB interfaces, which MongoDB itself is not pursuing.
 
-So do not get scared by [MongoDB’s Amazon DocumentDB bashing web site](https://www.isdocumentdbreallymongodb.com/) and self-serving compatibility ["evaluation"](https://www.mongodb.com/atlas-vs-amazon-documentdb/compatibility).
+So do not get scared by [MongoDB's Amazon DocumentDB bashing web site](https://www.isdocumentdbreallymongodb.com/) and self-serving compatibility ["evaluation"](https://www.mongodb.com/atlas-vs-amazon-documentdb/compatibility).
 Look into the functionality your application uses and plans to use and see whenever any of the MongoDB Alternatives support it.
 If they do not - let them know what is important to you .
 With FerretDB as an Open Source Project, you can both [file an issue](https://github.com/FerretDB/FerretDB/issues) or scratch your own itch by contributing the feature you need.

diff --git a/website/blog/2022-05-16-using-cla-assistant-with-ferretdb.md b/website/blog/2022-05-16-using-cla-assistant-with-ferretdb.md
@@ -8,7 +8,7 @@ date: 2022-05-16
 ---
 
 Like many other open-source projects, FerretDB requires all contributors to sign [our Contributor License Agreement (CLA)](https://gist.github.com/ferretdb-bot/554e6a30bfcc1d954f3853b4aad95281) to protect them from liability.
-(Please note that our CLA does include a transfer of copyright and we don’t use it to relicense FerretDB; but that all is a topic of the future blog post.)
+(Please note that our CLA does include a transfer of copyright and we don't use it to relicense FerretDB; but that all is a topic of the future blog post.)
 
 ![CLA Assistant](/img/blog/cla3.jpg)
 
@@ -21,7 +21,7 @@ Recently, we released FerretDB 0.2 which implements enough functionality for CLA
 Although FerretDB is [not production-ready yet](https://github.com/FerretDB/FerretDB/#scope-and-current-state), we are big fans of dogfooding, so we already run our own instance at [cla.ferretdb.io](https://cla.ferretdb.io) and use it in FerretDB development.
 In this blog post, we describe how you can host your installation using only open-source software.
 
-Let’s start with FerretDB and PostgreSQL.
+Let's start with FerretDB and PostgreSQL.
 We will use Docker Compose to run everything in Docker containers.
 Put the following into the docker-compose.yml file:
 
@@ -45,10 +45,10 @@ services:
 
 The first service starts PostgreSQL and creates "ferretdb" database, with data stored on the host system in `./data/postgres` directory.
 That ensures that data is not lost when you recreate this Compose project and makes the simplest way to do backups (by just copying this directory) possible.
-Of course, without more advanced backup solutions and with authentication disabled, that’s not a fully production-ready deployment, but good enough for an example.
+Of course, without more advanced backup solutions and with authentication disabled, that's not a fully production-ready deployment, but good enough for an example.
 
 The second service starts FerretDB which would connect to this PostgreSQL instance and listen on the standard MongoDB port.
-FerretDB starts very fast and exits if it can’t connect to PostgreSQL; `restart: on-failure` ensures that it is restarted in that case.
+FerretDB starts very fast and exits if it can't connect to PostgreSQL; `restart: on-failure` ensures that it is restarted in that case.
 
 Now we need to start CLA Assistant itself.
 They do not provide a prebuilt Docker image, but it is easy to build ourselves.
@@ -67,15 +67,15 @@ Next, we will need to register an OAuth App [there](https://github.com/settings/
 
 ![Register an Oauth App](/img/blog/cla1.jpg)
 
-App’s Authorization callback URL should be `https://<domain>/auth/github/callback`.
+App's Authorization callback URL should be `https://<domain>/auth/github/callback`.
 
 We also should register a [machine user account (a.k.a. bot)](https://docs.github.com/en/get-started/learning-about-github/types-of-github-accounts#personal-accounts) on GitHub and get a personal access token [there](https://github.com/settings/tokens) that will be used to call GitHub API on behalf of not authenticated users:
 
 ![Get personal token access](/img/blog/cla2.jpg)
 
 The only required scope is `public_repo`.
 
-Now, let’s add CLA Assistant to our Docker Compose configuration:
+Now, let's add CLA Assistant to our Docker Compose configuration:
 
 ```yaml
 services:
@@ -113,7 +113,7 @@ services:
       - ./Caddyfile:/etc/caddy/Caddyfile:ro
 ```
 
-Caddy will listen on both HTTP and HTTPS ports, and retrieve the TLS certificate from Let’s Encrypt that will be stored in `./data/caddy` on the host.
+Caddy will listen on both HTTP and HTTPS ports, and retrieve the TLS certificate from Let's Encrypt that will be stored in `./data/caddy` on the host.
 For that, we need to create a file called `Caddyfile` on the host next to docker-compose.yml with the following content:
 
 ```text
@@ -123,9 +123,9 @@ For that, we need to create a file called `Caddyfile` on the host next to docker
   }
 ```
 
-Email is used by Let’s Encrypt to contact you if [something goes wrong](https://letsencrypt.org/docs/expiration-emails/).
+Email is used by Let's Encrypt to contact you if [something goes wrong](https://letsencrypt.org/docs/expiration-emails/).
 
-That’s all with the configuration!
+That's all with the configuration!
 Now we can start our containers with `docker-compose up --detach`,
 start following logs with `docker-compose logs -f`,
 and open our domain in the browser to login with GitHub and configure our first CLA.

diff --git a/...blog/2022-06-27-developers-need-ferretdb-stackoverflow-developer-survey-2022.md b/...blog/2022-06-27-developers-need-ferretdb-stackoverflow-developer-survey-2022.md
@@ -18,20 +18,20 @@ When it comes to databases, this year, we see close to 70k responses, and the su
 
 When it comes to document, or NoSQL databases, MongoDB is still the undisputed leader, and is heavily contesting the popularity of relational databases.
 
-It is hard to think that any of the excitement comes from them adopting the [SSPL license](https://ssplisbad.com/) or that MongoDB’s managed offering, MongoDB Atlas, is probably mostly running on proprietary code these days.
+It is hard to think that any of the excitement comes from them adopting the [SSPL license](https://ssplisbad.com/) or that MongoDB's managed offering, MongoDB Atlas, is probably mostly running on proprietary code these days.
 
 The excitement undoubtedly comes from MongoDB getting developer experience right.
 We cannot praise MongoDB enough for changing the database industry by focusing on developer experience itself.
 Developer experience with some of the relational databases of the past decades were questionable, at best.
-I hear the uproar of many DBAs as I am writing this, but let’s face it: most developers are not interested in operating a database, and definitely not interested in debugging, interfacing, replication, and the like.
+I hear the uproar of many DBAs as I am writing this, but let's face it: most developers are not interested in operating a database, and definitely not interested in debugging, interfacing, replication, and the like.
 
-However, one needs to remember that MongoDB’s great developer experience comes with the high cost of vendor lock-in.
+However, one needs to remember that MongoDB's great developer experience comes with the high cost of vendor lock-in.
 There is simply no real open source alternative to MongoDB, and absolutely no compatible alternative to MongoDB Atlas.
 
 Back in 2016, shortly after launching MongoDB Atlas, MongoDB [published a blog post on the subject](https://www.mongodb.com/blog/post/avoiding-the-dark-side-of-the-cloud-platform-lock-in), and argues that MongoDB Atlas does not come with lock-in risks, since it runs on different cloud providers.
 They also claimed back then that MongoDB Atlas is running the same software as MongoDB.
 
-We don’t think that their claims hold true anymore.
+We don't think that their claims hold true anymore.
 You may be able to use different cloud providers, but you will still be in the mercy of MongoDB Inc, who licenses MongoDB to the cloud providers themselves.
 Note that at the time of publishing the above referenced blog post, MongoDB was still licensed under Apache 2.0, which is no longer the case.
 Nowadays, MongoDB Atlas does a lot more than on prem MongoDB, and the source code for those features are nowhere to be seen.

diff --git a/website/blog/2022-06-28-new-release-ferretdb-0-4-0.md b/website/blog/2022-06-28-new-release-ferretdb-0-4-0.md
@@ -8,7 +8,7 @@ tags: [release]
 date: 2022-06-28
 ---
 
-We are happy to announce that [FerretDB’s newest 0.4.0 release is now available on GitHub,](https://github.com/FerretDB/FerretDB/releases/tag/v0.4.0) with some exciting new features and fixes in it.
+We are happy to announce that [FerretDB's newest 0.4.0 release is now available on GitHub,](https://github.com/FerretDB/FerretDB/releases/tag/v0.4.0) with some exciting new features and fixes in it.
 
 ![New FerretDB release 0.4.0](/img/blog/4ferrets.webp)
 
@@ -18,9 +18,9 @@ We wish to thank everyone in the community who contributed to this release, eith
 Special thanks to [ribaraka](https://github.com/ribaraka) and [fenogentov](https://github.com/fenogentov) for their sustained efforts.
 
 Since 0.3.0, we are getting more and more user reports from those early adopters, who were curious enough to go ahead and replace their MongoDB instances with FerretDB - with success!
-The feedback we are getting is invaluable, though your mileage may vary based on the complexity of your application’s database needs.
+The feedback we are getting is invaluable, though your mileage may vary based on the complexity of your application's database needs.
 
-As mentioned before, we are already compatible with applications, like SAP’s [CLA assistant](https://github.com/cla-assistant), and there will be many more to come in the next couple of months.
+As mentioned before, we are already compatible with applications, like SAP's [CLA assistant](https://github.com/cla-assistant), and there will be many more to come in the next couple of months.
 
 We anticipate that with 0.4.0, we are getting several steps closer to providing an open source MongoDB database experience for those who care about avoiding vendor lock-in.
 
@@ -33,7 +33,7 @@ With this release, we are adding support for specific field operators such as `$
 
 We are also adding support for array querying and the `$elemMatch` array query operator.
 
-Stubs were also added for features related to MongoDB’s Free Monitoring in preparation to implement such a feature in the future.
+Stubs were also added for features related to MongoDB's Free Monitoring in preparation to implement such a feature in the future.
 This is a feature which exists since MongoDB 4.0, and provides support for getting data from your running instances, such as resource utilization and execution times.
 
 ## Added support for Tigris

diff --git a/website/blog/2022-07-27-new-ferretdb-minor-release-0-5-1.md b/website/blog/2022-07-27-new-ferretdb-minor-release-0-5-1.md
@@ -19,7 +19,7 @@ A major version 0.y.z every month,, followed by a minor or patch release two wee
 Our plan is to release 1.0.0 by the end of the year, which would be the first FerretDB release recommended to be used as a replacement for MongoDB.
 You can [check out our roadmap on GitHub](http://www.github.com/orgs/FerretDB/projects/2).
 
-In this month’s patch release, we added features, some of the notable ones are:
+In this month's patch release, we added features, some of the notable ones are:
 
 **Array Query Operators, now all 3 of them!**
 

diff --git a/website/blog/2022-09-20-how-to-contribute-to-open-source-2022.md b/website/blog/2022-09-20-how-to-contribute-to-open-source-2022.md
@@ -54,22 +54,22 @@ So, a GitHub account might be helpful or even crucial if you want to start contr
 GitHub has [detailed instructions](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account) for account creation.
 
 An important note here is that a free GitHub account will be more than enough.
-You don’t need any paid features to become an open-source contributor.
+You don't need any paid features to become an open-source contributor.
 
 Most likely, you might need an IDE or a code editor.
 At FerretDB, different engineers have their own preferences, but for your first steps in the open-source world, [Visual Studio Code](https://code.visualstudio.com/) is a good place to start.
-It supports all the popular formats and programming languages; it has handy integration with GitHub and other valuable tools, and, of course, it’s free.
+It supports all the popular formats and programming languages; it has handy integration with GitHub and other valuable tools, and, of course, it's free.
 
 In addition, Hacktoberfest's website has [a nice list of resources for beginners](https://hacktoberfest.com/participation/#beginner-resources).
 Check them out for further information.
 
 ### 2. Find the right project for Hacktoberfest open-source contributions
 
 Even though plenty of communities are open and friendly, not all the projects and issues would be suitable for first-time contributors.
-It’s essential to find some "low-hanging fruit" that will give you inspiration for future contributions.
+It's essential to find some "low-hanging fruit" that will give you inspiration for future contributions.
 
 On GitHub, it might make sense to look for "good-first-issue" labels.
-Usually, issues that are marked with such a label don’t require special knowledge about the project.
+Usually, issues that are marked with such a label don't require special knowledge about the project.
 
 There is one more tradition here, in October, some open source projects mark their issues with the "[hacktoberfest](https://github.com/search?q=label%3Ahacktoberfest&type=issues)" label, and such issues are often suitable for first-time contributors.
 
@@ -79,7 +79,7 @@ So, if you are looking for something to contribute to, take a look at the good f
 ### 3. Select a good first issue and read the contribution guidelines
 
 You found some projects with good first issues.
-What’s next?
+What's next?
 It is essential to check that you understand the issue and how to implement it.
 
 Before jumping into implementation, it might make sense to take a look at the README document and CONTRIBUTING guidelines of the repository.
@@ -88,7 +88,7 @@ Quite often, the projects follow some good practices that help contributors, and
 Also, many projects offer chats where contributors can ask any questions.
 
 At FerretDB, we use Slack for our contributors and community, and we also offer weekly Open Office Hours calls.
-Don’t hesitate to join us!
+Don't hesitate to join us!
 You can find details in our [README](https://github.com/ferretdb/ferretdb#community).
 
 By the way, the contributing guidelines or documentation might be the most suitable for first-time contributors!
@@ -124,12 +124,12 @@ For example, GitHub [offers documentation](https://docs.github.com/en/desktop/co
 And, of course, after the changes are committed, they also need to be [pushed](https://docs.github.com/en/desktop/contributing-and-collaborating-using-github-desktop/making-changes-in-a-branch/pushing-changes-to-github).
 
 At FerretDB, we prefer to commit and push as often as possible.
-Usually, we don’t wait for a feature to be fully implemented, a tiny valuable piece of code can be pushed to a remote branch, so the changes won’t be lost even if the local environment gets broken.
+Usually, we don't wait for a feature to be fully implemented, a tiny valuable piece of code can be pushed to a remote branch, so the changes won't be lost even if the local environment gets broken.
 
 ### 7. Make your first Pull Request
 
 So, your changes are ready and pushed to your fork?
-It’s time to create your first pull request!
+It's time to create your first pull request!
 As usual, GitHub has a [detailed guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) for it.
 Various projects might follow some practices to help contributors have their changes accepted as quickly as possible.
 
@@ -146,7 +146,7 @@ Congratulations!
 At FerretDB, we welcome all the open source contributors!
 From feature implementations to fixing typos in our documentation - we value everything!
 
-Whether it’s for Hacktoberfest or otherwise, you are welcome to take a look at [FerretDB projects](https://github.com/FerretDB/) and find something that interests you.
+Whether it's for Hacktoberfest or otherwise, you are welcome to take a look at [FerretDB projects](https://github.com/FerretDB/) and find something that interests you.
 To simplify the process, we prepared the [contributing guidelines](https://github.com/FerretDB/FerretDB/blob/main/CONTRIBUTING.md) to help you find something to work on, set up the development environment, prepare a pull request and pass code review.
 
 Are you looking forward to submitting your first pull request to FerretDB?
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		FROM ghcr.io/ferretdb/ferretdb-textlint:13.3.2-3
		FROM ghcr.io/ferretdb/ferretdb-textlint:13.3.2-4
Original file line number	Diff line number	Diff line change
		@@ -1 +1,3 @@
		FROM davidanson/markdownlint-cli2:v0.7.1

		ENTRYPOINT [ "markdownlint-cli2-config" ]