diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5fa9759fe..00e87ff8e 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -3,4 +3,4 @@ **Related issue** -**(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** diff --git a/BUILDING.md b/BUILDING.md index 9e8458306..81b70507c 100644 --- a/BUILDING.md +++ b/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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f9ebd847..f59ba4fa4 100644 --- a/CONTRIBUTING.md +++ b/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 [security@docker.com](mailto:security@docker.com). -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,11 +39,11 @@ 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: @@ -51,7 +51,7 @@ When reporting issues, always include: * 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. diff --git a/README.md b/README.md index 516eb6f1e..213b0e66d 100644 --- a/README.md +++ b/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 diff --git a/docs/reference/compose.md b/docs/reference/compose.md index e1b2c1fd0..d512fb2ac 100644 --- a/docs/reference/compose.md +++ b/docs/reference/compose.md @@ -55,7 +55,7 @@ Docker Compose You can use compose subcommand, `docker compose [-f ...] [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. diff --git a/docs/reference/compose_convert.md b/docs/reference/compose_convert.md index 1eb1bf05a..9688647d9 100644 --- a/docs/reference/compose_convert.md +++ b/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` diff --git a/docs/reference/compose_exec.md b/docs/reference/compose_exec.md index 9dd818b9f..b9f5ae2d5 100644 --- a/docs/reference/compose_exec.md +++ b/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. diff --git a/docs/reference/compose_ls.md b/docs/reference/compose_ls.md index b172c7f3a..b556e493f 100644 --- a/docs/reference/compose_ls.md +++ b/docs/reference/compose_ls.md @@ -17,4 +17,4 @@ List running compose projects ## Description -List Compose projects running on platform. \ No newline at end of file +Lists running Compose projects. \ No newline at end of file diff --git a/docs/reference/compose_ps.md b/docs/reference/compose_ps.md index edac93106..35c254024 100644 --- a/docs/reference/compose_ps.md +++ b/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 . ### 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) ### Filter containers by status (--filter) -The [`--status` flag](#status) is a convenience shorthand for the `--filter status=` +The [`--status` flag](#status) is a convenient shorthand for the `--filter 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=` -option, but additional filter options may be added in future. +option, but additional filter options may be added in the future. diff --git a/docs/reference/docker_compose.yaml b/docs/reference/docker_compose.yaml index acf60695f..c0512717c 100644 --- a/docs/reference/docker_compose.yaml +++ b/docs/reference/docker_compose.yaml @@ -4,7 +4,7 @@ long: |- You can use compose subcommand, `docker compose [-f ...] [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. diff --git a/docs/reference/docker_compose_convert.yaml b/docs/reference/docker_compose_convert.yaml index 2ba63901e..d19132219 100644 --- a/docs/reference/docker_compose_convert.yaml +++ b/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...] diff --git a/docs/reference/docker_compose_exec.yaml b/docs/reference/docker_compose_exec.yaml index ba357ae8f..fe0a0833c 100644 --- a/docs/reference/docker_compose_exec.yaml +++ b/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 diff --git a/docs/reference/docker_compose_ls.yaml b/docs/reference/docker_compose_ls.yaml index e64081de5..0b251f7ec 100644 --- a/docs/reference/docker_compose_ls.yaml +++ b/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 diff --git a/docs/reference/docker_compose_ps.yaml b/docs/reference/docker_compose_ps.yaml index 4e40f6f7b..19beb02c8 100644 --- a/docs/reference/docker_compose_ps.yaml +++ b/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=` + The [`--status` flag](#status) is a convenient shorthand for the `--filter 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=` - 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