Proofread

Signed-off-by: Bagrat Lazaryan <bagrat@stokhastik.net>
Co-authored-by: Laura Brehm <laurabrehm@hey.com>
Co-authored-by: Allie Sadler <102604716+aevesdocker@users.noreply.github.com>

01-status.md

@@ -12,7 +12,7 @@ exposing Linux kernel specific configuration options, but also some Windows cont
 We acknowledge that no Compose implementation is expected to support all attributes, and that support for some properties
 is platform dependent and can only be confirmed at runtime. The definition of a versioned schema to control the supported
 properties in a Compose file, established by the [docker-compose](https://github.com/docker/compose) tool where the Compose
-file format was designed, doesn't offer any guarantee to the end-user attributes will be actually implemented.
+file format was designed, doesn't offer any guarantee to the end-user that attributes will be actually implemented.
 
 The specification defines the expected configuration syntax and behavior. Unless noted, supporting any of these is OPTIONAL.
 

03-compose-file.md

@@ -61,17 +61,17 @@ services:
 ```
 
 - Compose application model parsed with no profile enabled only contains the `foo` service.
-- If profile `test` is enabled, model contains the services `bar` and `baz` which are enabled by the
-  `test` profile and service `foo` which is always enabled.
-- If profile `debug` is enabled, model contains both `foo` and `zot` services, but not `bar` and `baz`
+- If profile `test` is enabled, model contains the services `bar` and `baz`, which are enabled by the
+  `test` profile, and service `foo`, which is always enabled.
+- If profile `debug` is enabled, model contains both `foo` and `zot` services, but not `bar` and `baz`,
   and as such the model is invalid regarding the `depends_on` constraint of `zot`.
 - If profiles `debug` and `test` are enabled, model contains all services: `foo`, `bar`, `baz` and `zot`.
 - If Compose implementation is executed with `bar` as explicit service to run, it and the `test` profile
   will be active even if `test` profile is not enabled _by the user_.
 - If Compose implementation is executed with `baz` as explicit service to run, the service `baz` and the
   profile `test` will be active and `bar` will be pulled in by the `depends_on` constraint.
 - If Compose implementation is executed with `zot` as explicit service to run, again the model will be
-  invalid regarding the `depends_on` constraint of `zot` since `zot` and `bar` have no common `profiles`
+  invalid regarding the `depends_on` constraint of `zot`, since `zot` and `bar` have no common `profiles`
   listed.
 - If Compose implementation is executed with `zot` as explicit service to run and profile `test` enabled,
   profile `debug` is automatically enabled and service `bar` is pulled in as a dependency starting both

04-version-and-name.md

@@ -11,11 +11,11 @@ SHOULD warn the user. Compose implementations MAY offer options to ignore unknow
 
 ## Name top-level element
 
-Top-level `name` property is defined by the specification as project name to be used if user doesn't set one explicitly. 
+Top-level `name` property is defined by the specification as project name to be used if user doesn't set one explicitly.
 Compose implementations MUST offer a way for user to override this name, and SHOULD define a mechanism to compute a
-default project name, to be used if the top-level `name` element is not set.
+default project name to be used if the top-level `name` element is not set.
 
-Whenever project name is defined by top-level `name` or by some custom mechanism, it MUST be exposed for 
+Whenever project name is defined by top-level `name` or by some custom mechanism, it MUST be exposed for
 [interpolation](12-interpolation.md) and environment variable resolution as `COMPOSE_PROJECT_NAME`
 
 ```yml
@@ -26,4 +26,3 @@ services:
       - COMPOSE_PROJECT_NAME
     command: echo "I'm running ${COMPOSE_PROJECT_NAME}"
 ```
-

05-services.md

@@ -11,7 +11,7 @@ and whose values are service definitions. A service  definition contains the con
 container started for that service.
 
 Each service MAY also include a Build section, which defines how to create the Docker image for the service.
-Compose implementations MAY support building docker images using this service definition. If not implemented
+Compose implementations MAY support building docker images using this service definition. If not implemented,
 the Build section SHOULD be ignored and the Compose file MUST still be considered valid.
 
 Build support is an OPTIONAL aspect of the Compose specification, and is
@@ -616,7 +616,7 @@ extends:
   service: webapp
 ```
 
-If supported Compose implementations MUST process `extends` in the following way:
+If supported, Compose implementations MUST process `extends` in the following way:
 
 - `service` defines the name of the service being referenced as a base, for example `web` or `database`.
 - `file` is the location of a Compose configuration file defining that service.
@@ -629,7 +629,7 @@ The following restrictions apply to the service being referenced:
   that introduces a dependency on another service is incompatible with `extends`. The
   non-exhaustive list of such keys is: `links`, `volumes_from`, `container` mode (in `ipc`, `pid`,
   `network_mode` and `net`), `service` mode (in `ipc`, `pid` and `network_mode`), `depends_on`.
-- Services cannot have circular references with `extends`
+- Services cannot have circular references with `extends`.
 
 Compose implementations MUST return an error in all of these cases.
 
@@ -912,7 +912,7 @@ test: ["CMD-SHELL", "curl -f http://localhost || exit 1"]
 test: curl -f https://localhost || exit 1
 ```
 
-`NONE` disable the healthcheck, and is mostly useful to disable Healthcheck set by image. Alternatively
+`NONE` disables the healthcheck, and is mostly useful to disable Healthcheck set by image. Alternatively,
 the healthcheck set by the image can be disabled by setting `disable: true`:
 
 ```yml
@@ -966,10 +966,10 @@ The init binary that is used is platform specific.
 values are platform specific, but Compose specification defines specific values
 which MUST be implemented as described if supported:
 
-- `shareable` which gives the container own private IPC namespace, with a
+- `shareable` which gives the container its own private IPC namespace, with a
   possibility to share it with other containers.
-- `service:{name}` which makes the container join another (`shareable`)
-   container's IPC namespace.
+- `service:{name}` which makes the container join another container's
+  (`shareable`) IPC namespace.
 
 ```yml
     ipc: "shareable"
@@ -1061,10 +1061,10 @@ are platform specific. Driver specific options can be set with `options` as key-
 
 ### network_mode
 
-`network_mode` set service containers network mode. Available values are platform specific, but Compose
-specification define specific values which MUST be implemented as described if supported:
+`network_mode` sets service containers network mode. Available values are platform specific, but Compose
+specification defines specific values which MUST be implemented as described if supported:
 
-- `none` which disable all container networking
+- `none` which disables all container networking
 - `host` which gives the container raw access to host's network interface
 - `service:{name}` which gives the containers access to the specified service only
 
@@ -1258,7 +1258,7 @@ There is a performance penalty for applications that swap memory to disk often.
 
 ### oom_kill_disable
 
-If `oom_kill_disable` is set Compose implementation MUST configure the platform so it won't kill the container in case
+If `oom_kill_disable` is set, Compose implementation MUST configure the platform so it won't kill the container in case
 of memory starvation.
 
 ### oom_score_adj
@@ -1346,7 +1346,7 @@ expressed in the short form.
 
 - `target`: the container port
 - `published`: the publicly exposed port. Can be set as a range using syntax `start-end`, so it is defined as a string, then actual port SHOULD be assigned within this range based on available ports.
-- `host_ip`: the Host IP mapping, unspecified means all network interfaces (`0.0.0.0`) 
+- `host_ip`: the Host IP mapping, unspecified means all network interfaces (`0.0.0.0`)
 - `protocol`: the port protocol (`tcp` or `udp`), unspecified means any protocol
 - `mode`: `host` for publishing a host port on each node, or `ingress` for a port to be load balanced.
 
@@ -1387,7 +1387,7 @@ If present, `profiles` SHOULD follow the regex format of `[a-zA-Z0-9][a-zA-Z0-9_
   `if_not_present` SHOULD be considered an alias for this value for backward compatibility
 * `build`: Compose implementations SHOULD build the image. Compose implementations SHOULD rebuild the image if already present.
 
-If `pull_policy` and `build` both presents, Compose implementations SHOULD build the image by default. Compose implementations MAY override this behavior in the toolchain.
+If `pull_policy` and `build` are both present, Compose implementations SHOULD build the image by default. Compose implementations MAY override this behavior in the toolchain.
 
 ### read_only
 
@@ -1397,10 +1397,10 @@ If `pull_policy` and `build` both presents, Compose implementations SHOULD build
 
 `restart` defines the policy that the platform will apply on container termination.
 
-- `no`: The default restart policy. Does not restart a container under any circumstances.
+- `no`: The default restart policy. Does not restart the container under any circumstances.
 - `always`: The policy always restarts the container until its removal.
-- `on-failure`: The policy restarts a container if the exit code indicates an error.
-- `unless-stopped`: The policy restarts a container irrespective of the exit code but will stop
+- `on-failure`: The policy restarts the container if the exit code indicates an error.
+- `unless-stopped`: The policy restarts the container irrespective of the exit code but will stop
   restarting when the service is stopped or removed.
 
 ```yml
@@ -1436,7 +1436,7 @@ _DEPRECATED: use [deploy/replicas](deploy.md#replicas)_
 different syntax variants are supported: the short syntax and the long syntax.
 
 Compose implementations MUST report an error if the secret doesn't exist on the platform or isn't defined in the
-[`secrets`](09-secrets.md) section of this Compose file.
+[`secrets`](09-secrets.md) section of the Compose file.
 
 #### Short syntax
 
@@ -1587,12 +1587,12 @@ tmpfs:
 
 ### tty
 
-`tty` configure service container to run with a TTY.
+`tty` configures service container to run with a TTY.
 
 ### ulimits
 
-`ulimits` overrides the default ulimits for a container. Either specifies as a single limit as an integer or
-soft/hard limits as a mapping.
+`ulimits` overrides the default ulimits for a container. Specified either as an integer for a single limit
+or as mapping for soft/hard limits.
 
 ```yml
 ulimits:
@@ -1620,7 +1620,7 @@ userns_mode: "host"
 
 `volumes` defines mount host paths or named volumes that MUST be accessible by service containers.
 
-If the mount is a host path and only used by a single service, it MAY be declared as part of the service
+If the mount is a host path and is only used by a single service, it MAY be declared as part of the service
 definition instead of the top-level `volumes` key.
 
 To reuse a volume across multiple services, a named
@@ -1654,11 +1654,11 @@ The short syntax uses a single string with colon-separated values to specify a v
 
 - `VOLUME`: MAY be either a host path on the platform hosting containers (bind mount) or a volume name
 - `CONTAINER_PATH`: the path in the container where the volume is mounted
-- `ACCESS_MODE`: is a comma-separated `,` list of options and MAY be set to:
+- `ACCESS_MODE`: a comma-separated `,` list of options. MAY be set to:
   - `rw`: read and write access (default)
   - `ro`: read-only access
-  - `z`: SELinux option indicates that the bind mount host content is shared among multiple containers
-  - `Z`: SELinux option indicates that the bind mount host content is private and unshared for other containers
+  - `z`: SELinux option indicating that the bind mount host content is shared among multiple containers
+  - `Z`: SELinux option indicating that the bind mount host content is private and unshared for other containers
 
 > **Note**: The SELinux re-labeling bind mount option is ignored on platforms without SELinux.
 
@@ -1681,7 +1681,7 @@ expressed in the short form.
 - `read_only`: flag to set the volume as read-only
 - `bind`: configure additional bind options
   - `propagation`: the propagation mode used for the bind
-  - `create_host_path`: create a directory at the source path on host if there is nothing present. 
+  - `create_host_path`: create a directory at the source path on host if there is nothing present.
     Do nothing if there is something present at the path. This is automatically implied by short syntax
     for backward compatibility with docker-compose legacy.
   - `selinux`: the SELinux re-labeling option `z` (shared) or `Z` (private)
@@ -1711,5 +1711,5 @@ volumes_from:
 
 ### working_dir
 
-`working_dir` overrides the container's working directory from that specified by image (i.e. Dockerfile `WORKDIR`).
+`working_dir` overrides the container's working directory from that specified by the image (i.e. Dockerfile `WORKDIR`).
 

06-networks.md

@@ -8,7 +8,7 @@ Networks can be created by specifying the network name under a top-level `networ
 Services can connect to networks by specifying the network name under the service [`networks`](05-services.md#networks) subsection
 
 In the following example, at runtime, networks `front-tier` and `back-tier` will be created and the `frontend` service
-connected to the `front-tier` network and the `back-tier` network.
+will be connected to `front-tier` and `back-tier` networks.
 
 ```yml
 services:
@@ -40,9 +40,9 @@ Default and available values are platform specific. Compose specification MUST s
 
 #### host or none
 
-The syntax for using built-in networks such as `host` and `none` is different, as such networks implicitly exists outside
-the scope of the Compose implementation. To use them one MUST define an external network with the name `host` or `none` and
-an alias that the Compose implementation can use (`hostnet` or `nonet` in the following examples), then grant the service
+The syntax for using built-in networks such as `host` and `none` is different, as such networks implicitly exist outside
+the scope of the Compose implementation. To use them, one MUST define an external network with the name `host` or `none` and
+an alias that the Compose implementation can use (`hostnet` and `nonet` in the following examples), then grant the service
 access to that network using its alias.
 
 ```yml
@@ -83,7 +83,7 @@ driver_opts:
 
 ### attachable
 
-If `attachable` is set to `true`, then standalone containers SHOULD be able attach to this network, in addition to services.
+If `attachable` is set to `true`, then standalone containers SHOULD be able to attach to this network, in addition to services.
 If a standalone container attaches to the network, it can communicate with services and other standalone containers
 that are also attached to the network.
 
@@ -130,8 +130,8 @@ ipam:
 
 ### internal
 
-By default, Compose implementations MUST provides external connectivity to networks. `internal` when set to `true` allow to
-create an externally isolated network.
+By default, Compose implementations MUST provides external connectivity to networks. `internal`, when set to `true`, allows
+creating an externally isolated network.
 
 ### labels
 
@@ -158,10 +158,10 @@ Compose implementations MUST set `com.docker.compose.project` and `com.docker.co
 ### external
 
 If set to `true`, `external` specifies that this network’s lifecycle is maintained outside of that of the application.
-Compose Implementations SHOULD NOT attempt to create these networks, and raises an error if one doesn't exist.
+Compose Implementations SHOULD NOT attempt to create these networks, and SHOULD raise an error if one doesn't exist.
 
 If `external` is set to `true` and network configuration has other but `name` attributes set, considering resource is
-not managed by compose lifecycle, Compose Implementations SHOULD reject a Compose file as invalid.
+not managed by compose lifecycle, Compose Implementations SHOULD reject the Compose file as invalid.
 
 In the example below, `proxy` is the gateway to the outside world. Instead of attempting to create a network, Compose
 implementations SHOULD interrogate the platform for an existing network simply called `outside` and connect the

07-volumes.md

@@ -49,12 +49,12 @@ volumes:
 
 ### external
 
-If set to `true`, `external` specifies that this volume already exist on the platform and its lifecycle is managed outside
+If set to `true`, `external` specifies that this volume already exists on the platform and its lifecycle is managed outside
 of that of the application. Compose implementations MUST NOT attempt to create these volumes, and MUST return an error if they
 do not exist.
 
 If `external` is set to `true` and volume configuration has other but `name` attributes set, considering resource is
-not managed by compose lifecycle, Compose Implementations SHOULD reject a Compose file as invalid.
+not managed by compose lifecycle, Compose Implementations SHOULD reject the Compose file as invalid.
 
 
 In the example below, instead of attempting to create a volume called
@@ -107,7 +107,7 @@ volumes:
     name: "my-app-data"
 ```
 
-It can also be used in conjunction with the `external` property. Doing so the name of the volume used to lookup for
+It can also be used in conjunction with the `external` property. In that case the name of the volume used to lookup for
 actual volume on platform is set separately from the name used to refer to it within the Compose file:
 
 ```yml
@@ -117,7 +117,7 @@ volumes:
       name: actual-name-of-volume
 ```
 
-This make it possible to make this lookup name a parameter of a Compose file, so that the model ID for volume is
+This makes it possible to make this lookup name a parameter of the Compose file, so that the model ID for volume is
 hard-coded but the actual volume ID on platform is set at runtime during deployment:
 
 ```yml