docs: fix grammatical issues (docker#9997)

Signed-off-by: Umar Chowdhury <[email protected]>
Co-authored-by: Milas Bowman <[email protected]>

.github/PULL_REQUEST_TEMPLATE.md

@@ -3,4 +3,4 @@
 **Related issue**
 <!-- If this is a bug fix, make sure your description includes "fixes #xxxx", or "closes #xxxx" -->
 
-**(not mandatory) A picture of a cute animal, if possible in relation with what you did**
+**(not mandatory) A picture of a cute animal, if possible in relation to what you did**

BUILDING.md

@@ -36,7 +36,7 @@ make test
 If you need to update a golden file simply do `go test ./... -test.update-golden`.
 
 ### End-to-end tests
-To run e2e tests, the Compose CLI binary need to be build. All the commands to run e2e tests propose a version
+To run e2e tests, the Compose CLI binary needs to be built. All the commands to run e2e tests propose a version
 with the prefix `build-and-e2e` to first build the CLI before executing tests.
 
 Note that this requires a local Docker Engine to be running.
@@ -84,8 +84,8 @@ make build-and-e2e-compose-standalone
 ## Releases
 
 To create a new release:
-* Check that the CI is green on the main branch for commit you want to release
-* Run the release Github Actions workflow with a tag of the form vx.y.z following existing tags.
+* Check that the CI is green on the main branch for the commit you want to release
+* Run the release Github Actions workflow with a tag of form vx.y.z following existing tags.
 
 This will automatically create a new tag, release and make binaries for
 Windows, macOS, and Linux available for download on the

CONTRIBUTING.md

@@ -22,12 +22,12 @@ start participating.
 The Docker maintainers take security seriously. If you discover a security
 issue, please bring it to their attention right away!
 
-Please **DO NOT** file a public issue, instead send your report privately to
+Please **DO NOT** file a public issue, instead, send your report privately to
 [[email protected]](mailto:[email protected]).
 
-Security reports are greatly appreciated and we will publicly thank you for it.
+Security reports are greatly appreciated and we will publicly thank you for them.
 We also like to send gifts—if you're into Docker swag, make sure to let
-us know. We currently do not offer a paid security bounty program, but are not
+us know. We currently do not offer a paid security bounty program but are not
 ruling it out in the future.
 
 
@@ -39,19 +39,19 @@ and will thank you for it!
 
 Check that [our issue database](https://github.com/docker/compose/labels/Docker%20Compose%20V2)
 doesn't already include that problem or suggestion before submitting an issue.
-If you find a match, you can use the "subscribe" button to get notified on
+If you find a match, you can use the "subscribe" button to get notified of
 updates. Do *not* leave random "+1" or "I have this too" comments, as they
 only clutter the discussion, and don't help to resolve it. However, if you
 have ways to reproduce the issue or have additional information that may help
-resolving the issue, please leave a comment.
+resolve the issue, please leave a comment.
 
 When reporting issues, always include:
 
 * The output of `docker version`.
 * The output of `docker context show`.
 * The output of `docker info`.
 
-Also include the steps required to reproduce the problem if possible and
+Also, include the steps required to reproduce the problem if possible and
 applicable. This information will help us review and fix your issue faster.
 When sending lengthy log files, consider posting them as a gist
 (https://gist.github.com).
@@ -124,7 +124,7 @@ Fork the repository and make changes on your fork in a feature branch:
     issue.
 
 Submit unit tests for your changes. Go has a great test framework built in; use
-it! Take a look at existing tests for inspiration. Also end-to-end tests are
+it! Take a look at existing tests for inspiration. Also, end-to-end tests are
 available. Run the full test suite, both unit tests and e2e tests on your
 branch before submitting a pull request. See [BUILDING.md](BUILDING.md) for
 instructions to build and run tests.
@@ -145,7 +145,7 @@ suggested modifications and push additional commits to your feature branch. Post
 a comment after pushing. New commits show up in the pull request automatically,
 but the reviewers are notified only when you comment.
 
-Pull requests must be cleanly rebased on top of master without multiple branches
+Pull requests must be cleanly rebased on top of the base branch without multiple branches
 mixed into the PR.
 
 **Git tip**: If your PR no longer merges cleanly, use `rebase master` in your
@@ -165,7 +165,7 @@ changes in the same pull request so that a revert would remove all traces of
 the feature or fix.
 
 Include an issue reference like `Closes #XXXX` or `Fixes #XXXX` in the pull
-request description that close an issue. Including references automatically
+request description that closes an issue. Including references automatically
 closes the issue on a merge.
 
 Please do not add yourself to the `AUTHORS` file, as it is regenerated regularly
@@ -256,7 +256,7 @@ your help to keep it that way. To help with this we've come up with some general
 guidelines for the community as a whole:
 
 * Be nice: Be courteous, respectful and polite to fellow community members:
-  no regional, racial, gender, or other abuse will be tolerated. We like
+  no regional, racial, gender or other abuse will be tolerated. We like
   nice people way better than mean ones!
 
 * Encourage diversity and participation: Make everyone in our community feel
@@ -270,10 +270,10 @@ guidelines for the community as a whole:
 
 * Stay on topic: Make sure that you are posting to the correct channel and
   avoid off-topic discussions. Remember when you update an issue or respond
-  to an email you are potentially sending to a large number of people. Please
-  consider this before you update. Also remember that nobody likes spam.
+  to an email you are potentially sending it to a large number of people. Please
+  consider this before you update. Also, remember that nobody likes spam.
 
-* Don't send email to the maintainers: There's no need to send email to the
+* Don't send emails to the maintainers: There's no need to send emails to the
   maintainers to ask them to investigate an issue or to take a look at a
   pull request. Instead of sending an email, GitHub mentions should be
   used to ping maintainers to review a pull request, a proposal or an
@@ -287,7 +287,7 @@ to result in a solid, consistent codebase.
 
 It is possible that the code base does not currently comply with these
 guidelines. We are not looking for a massive PR that fixes this, since that
-goes against the spirit of the guidelines. All new contributions should make a
+goes against the spirit of the guidelines. All new contributors should make their
 best effort to clean up and make the code base better than they left it.
 Obviously, apply your best judgement. Remember, the goal here is to make the
 code base easier for humans to navigate and understand. Always keep that in
@@ -301,7 +301,7 @@ The rules:
 3. All code should follow the guidelines covered in [Effective
    Go](http://golang.org/doc/effective_go.html) and [Go Code Review
    Comments](https://github.com/golang/go/wiki/CodeReviewComments).
-4. Comment the code. Tell us the why, the history and the context.
+4. Include code comments. Tell us the why, the history and the context.
 5. Document _all_ declarations and methods, even private ones. Declare
    expectations, caveats and anything else that may be important. If a type
    gets exported, having the comments already there will ensure it's ready.

README.md

@@ -10,7 +10,7 @@
 
 Docker Compose is a tool for running multi-container applications on Docker
 defined using the [Compose file format](https://compose-spec.io).
-A Compose file is used to define how the one or more containers that make up
+A Compose file is used to define how one or more containers that make up
 your application are configured.
 Once you have a Compose file, you can create and start your application with a
 single command: `docker compose up`.
@@ -47,7 +47,7 @@ Or copy it into one of these folders to install it system-wide:
 Quick Start
 -----------
 
-Using Docker Compose is basically a three-step process:
+Using Docker Compose is a three-step process:
 1. Define your app's environment with a `Dockerfile` so it can be
    reproduced anywhere.
 2. Define the services that make up your app in `docker-compose.yml` so

docs/reference/compose.md

@@ -55,7 +55,7 @@ Docker Compose
 You can use compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage
 multiple services in Docker containers.
 
-### Use `-f` to specify name and path of one or more Compose files
+### Use `-f` to specify the name and path of one or more Compose files
 Use the `-f` flag to specify the location of a Compose configuration file.
 
 #### Specifying multiple Compose files
@@ -118,8 +118,8 @@ Each configuration has a project name. If you supply a `-p` flag, you can specif
 specify the flag, Compose uses the current directory name.
 Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable.
 
-Most compose subcommand can be ran without a compose file, just passing
-project name to retrieve the relevant resources.
+Many Compose subcommands can be run without a Compose file by passing
+the project name.
 
 ```console
 $ docker compose -p my_project ps -a
@@ -145,10 +145,10 @@ Profiles can also be set by `COMPOSE_PROFILES` environment variable.
 You can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags.
 
 Setting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag,
-`COMPOSE_PROJECT_NAME` environment variable does the same for to the `-p` flag,
-and so does `COMPOSE_PROFILES` environment variable for to the `--profiles` flag.
+`COMPOSE_PROJECT_NAME` environment variable does the same as the `-p` flag,
+and `COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag.
 
-If flags are explicitly set on command line, associated environment variable is ignored
+If flags are explicitly set on the command line, the associated environment variable is ignored.
 
 Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` will stop docker compose from detecting orphaned
 containers for the project.

docs/reference/compose_convert.md

@@ -29,8 +29,8 @@ Converts the compose file to platform's canonical format
 
 ## Description
 
-`docker compose convert` render the actual data model to be applied on target platform. When used with Docker engine,
-it merges the Compose files set by `-f` flags, resolves variables in Compose file, and expands short-notation into
-fully defined Compose model.
+`docker compose convert` renders the actual data model to be applied on the target platform. When used with the Docker engine,
+it merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into
+the canonical format.
 
 To allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`

docs/reference/compose_exec.md

@@ -22,5 +22,5 @@ Execute a command in a running container.
 
 This is the equivalent of `docker exec` targeting a Compose service.
 
-With this subcommand you can run arbitrary commands in your services. Commands are by default allocating a TTY, so
+With this subcommand, you can run arbitrary commands in your services. Commands allocate a TTY by default, so
 you can use a command such as `docker compose exec web sh` to get an interactive prompt.

docs/reference/compose_ls.md

@@ -17,4 +17,4 @@ List running compose projects
 
 ## Description
 
-List Compose projects running on platform.
+Lists running Compose projects.

docs/reference/compose_ps.md

@@ -35,7 +35,7 @@ example-foo-1  "/docker-entrypoint.…"   foo       running      0.0.0.0:8080->8
 
 By default, the `docker compose ps` command uses a table ("pretty") format to
 show the containers. The `--format` flag allows you to specify alternative
-presentations for the output. Currently supported options are `pretty` (default),
+presentations for the output. Currently, supported options are `pretty` (default),
 and `json`, which outputs information about the containers as a JSON array:
 
 ```console
@@ -85,7 +85,7 @@ $ docker compose ps --format json | jq .
 ### <a name="status"></a> Filter containers by status (--status)
 
 Use the `--status` flag to filter the list of containers by status. For example,
-to show only containers that are running, or only containers that have exited:
+to show only containers that are running or only containers that have exited:
 
 ```console
 $ docker compose ps --status=running
@@ -99,7 +99,7 @@ example-bar-1  "/docker-entrypoint.…"   bar       exited (0)
 
 ### <a name="filter"></a> Filter containers by status (--filter)
 
-The [`--status` flag](#status) is a convenience shorthand for the `--filter status=<status>`
+The [`--status` flag](#status) is a convenient shorthand for the `--filter status=<status>`
 flag. The example below is the equivalent to the example from the previous section,
 this time using the `--filter` flag:
 
@@ -114,4 +114,4 @@ example-bar-1  "/docker-entrypoint.…"   bar       exited (0)
 ```
 
 The `docker compose ps` command currently only supports the `--filter status=<status>`
-option, but additional filter options may be added in future.
+option, but additional filter options may be added in the future.

docs/reference/docker_compose.yaml

@@ -4,7 +4,7 @@ long: |-
     You can use compose subcommand, `docker compose [-f <arg>...] [options] [COMMAND] [ARGS...]`, to build and manage
     multiple services in Docker containers.
 
-    ### Use `-f` to specify name and path of one or more Compose files
+    ### Use `-f` to specify the name and path of one or more Compose files
     Use the `-f` flag to specify the location of a Compose configuration file.
 
     #### Specifying multiple Compose files
@@ -67,8 +67,8 @@ long: |-
     specify the flag, Compose uses the current directory name.
     Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable.
 
-    Most compose subcommand can be ran without a compose file, just passing
-    project name to retrieve the relevant resources.
+    Many Compose subcommands can be run without a Compose file by passing
+    the project name.
 
     ```console
     $ docker compose -p my_project ps -a
@@ -94,10 +94,10 @@ long: |-
     You can set environment variables for various docker compose options, including the `-f`, `-p` and `--profiles` flags.
 
     Setting the `COMPOSE_FILE` environment variable is equivalent to passing the `-f` flag,
-    `COMPOSE_PROJECT_NAME` environment variable does the same for to the `-p` flag,
-    and so does `COMPOSE_PROFILES` environment variable for to the `--profiles` flag.
+    `COMPOSE_PROJECT_NAME` environment variable does the same as the `-p` flag,
+    and `COMPOSE_PROFILES` environment variable is equivalent to the `--profiles` flag.
 
-    If flags are explicitly set on command line, associated environment variable is ignored
+    If flags are explicitly set on the command line, the associated environment variable is ignored.
 
     Setting the `COMPOSE_IGNORE_ORPHANS` environment variable to `true` will stop docker compose from detecting orphaned
     containers for the project.

docs/reference/docker_compose_convert.yaml

@@ -2,9 +2,9 @@ command: docker compose convert
 aliases: docker compose convert, docker compose config
 short: Converts the compose file to platform's canonical format
 long: |-
-    `docker compose convert` render the actual data model to be applied on target platform. When used with Docker engine,
-    it merges the Compose files set by `-f` flags, resolves variables in Compose file, and expands short-notation into
-    fully defined Compose model.
+    `docker compose convert` renders the actual data model to be applied on the target platform. When used with the Docker engine,
+    it merges the Compose files set by `-f` flags, resolves variables in the Compose file, and expands short-notation into
+    the canonical format.
 
     To allow smooth migration from docker-compose, this subcommand declares alias `docker compose config`
 usage: docker compose convert [OPTIONS] [SERVICE...]

docs/reference/docker_compose_exec.yaml

@@ -3,7 +3,7 @@ short: Execute a command in a running container.
 long: |-
     This is the equivalent of `docker exec` targeting a Compose service.
 
-    With this subcommand you can run arbitrary commands in your services. Commands are by default allocating a TTY, so
+    With this subcommand, you can run arbitrary commands in your services. Commands allocate a TTY by default, so
     you can use a command such as `docker compose exec web sh` to get an interactive prompt.
 usage: docker compose exec [OPTIONS] SERVICE COMMAND [ARGS...]
 pname: docker compose

docs/reference/docker_compose_ls.yaml

@@ -1,6 +1,6 @@
 command: docker compose ls
 short: List running compose projects
-long: List Compose projects running on platform.
+long: Lists running Compose projects.
 usage: docker compose ls [OPTIONS]
 pname: docker compose
 plink: docker_compose.yaml

docs/reference/docker_compose_ps.yaml

@@ -85,7 +85,7 @@ examples: |-
 
     By default, the `docker compose ps` command uses a table ("pretty") format to
     show the containers. The `--format` flag allows you to specify alternative
-    presentations for the output. Currently supported options are `pretty` (default),
+    presentations for the output. Currently, supported options are `pretty` (default),
     and `json`, which outputs information about the containers as a JSON array:
 
     ```console
@@ -135,7 +135,7 @@ examples: |-
     ### Filter containers by status (--status) {#status}
 
     Use the `--status` flag to filter the list of containers by status. For example,
-    to show only containers that are running, or only containers that have exited:
+    to show only containers that are running or only containers that have exited:
 
     ```console
     $ docker compose ps --status=running
@@ -149,7 +149,7 @@ examples: |-
 
     ### Filter containers by status (--filter) {#filter}
 
-    The [`--status` flag](#status) is a convenience shorthand for the `--filter status=<status>`
+    The [`--status` flag](#status) is a convenient shorthand for the `--filter status=<status>`
     flag. The example below is the equivalent to the example from the previous section,
     this time using the `--filter` flag:
 
@@ -164,7 +164,7 @@ examples: |-
     ```
 
     The `docker compose ps` command currently only supports the `--filter status=<status>`
-    option, but additional filter options may be added in future.
+    option, but additional filter options may be added in the future.
 deprecated: false
 experimental: false
 experimentalcli: false