Compose freshness: startup order, profiles, lifecycle hooks, project name (docker#22949)

<!--Delete sections as needed -->

## Description

Freshness to a few how-tos pages. also fixes and closes
docker#21417

## Related issues or tickets

<!-- Related issues, pull requests, or Jira tickets -->

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

Author: aevesdocker

content/manuals/compose/how-tos/lifecycle.md

@@ -2,8 +2,8 @@
 title: Using lifecycle hooks with Compose
 linkTitle: Use lifecycle hooks
 weight: 20
-desription: How to use lifecycle hooks with Docker Compose
-keywords: cli, compose, lifecycle, hooks reference
+description: Learn how to use Docker Compose lifecycle hooks like post_start and pre_stop to customize container behavior.
+keywords: docker compose lifecycle hooks, post_start, pre_stop, docker compose entrypoint, docker container stop hooks, compose hook commands
 ---
 
 {{< summary-bar feature_name="Compose lifecycle hooks" >}}

content/manuals/compose/how-tos/profiles.md

@@ -85,6 +85,12 @@ If you want to enable all profiles at the same time, you can run `docker compose
 
 ## Auto-starting profiles and dependency resolution
 
+When you explicitly target a service on the command line that has one or more profiles assigned, you do not need to enable the profile manually as Compose runs that service regardless of whether its profile is activated. This is useful for running one-off services or debugging tools.
+
+Only the targeted service (and any of its declared dependencies via `depends_on`) is started. Other services that share the same profile will not be started unless:
+- They are also explicitly targeted, or
+- The profile is explicitly enabled using `--profile` or `COMPOSE_PROFILES`.
+
 When a service with assigned `profiles` is explicitly targeted on the command
 line its profiles are started automatically so you don't need to start them
 manually. This can be used for one-off services and debugging tools.
@@ -108,72 +114,19 @@ services:
 ```
 
 ```sh
-# Only start backend and db
+# Only start backend and db (no profiles involved)
 $ docker compose up -d
 
-# This runs db-migrations (and, if necessary, start db)
-# by implicitly enabling the profiles "tools"
+# Run the db-migrations service without manually enabling the 'tools' profile
 $ docker compose run db-migrations
 ```
 
-But keep in mind that `docker compose` only automatically starts the
-profiles of the services on the command line and not of any dependencies. 
-
-This means that any other services the targeted service `depends_on` should either:
-- Share a common profile 
-- Always be started, by omitting `profiles` or having a matching profile started explicitly
-
-```yaml
-services:
-  web:
-    image: web
-
-  mock-backend:
-    image: backend
-    profiles: ["dev"]
-    depends_on:
-      - db
-
-  db:
-    image: mysql
-    profiles: ["dev"]
-
-  phpmyadmin:
-    image: phpmyadmin
-    profiles: ["debug"]
-    depends_on:
-      - db
-```
-
-```sh
-# Only start "web"
-$ docker compose up -d
-
-# Start mock-backend (and, if necessary, db)
-# by implicitly enabling profiles "dev"
-$ docker compose up -d mock-backend
-
-# This fails because profiles "dev" is not enabled
-$ docker compose up phpmyadmin
-```
-
-Although targeting `phpmyadmin` automatically starts the profiles `debug`, it doesn't automatically start the profiles required by `db` which is `dev`. 
+In this example, `db-migrations` runs even though it is assigned to the tools profile, because it was explicitly targeted. The `db` service is also started automatically because it is listed in `depends_on`.
 
-To fix this you either have to add the `debug` profile to the `db` service:
-
-```yaml
-db:
-  image: mysql
-  profiles: ["debug", "dev"]
-```
-
-or start the `dev` profile explicitly:
-
-```console
-# Profiles "debug" is started automatically by targeting phpmyadmin
-$ docker compose --profile dev up phpmyadmin
-$ COMPOSE_PROFILES=dev docker compose up phpmyadmin
-```
+If the targeted service has dependencies that are also gated behind a profile, you must ensure those dependencies are either: 
+ - In the same profile
+ - Started separately
+ - Not assigned to any profile so are always enabled
 
 ## Stop application and services with specific profiles
 
@@ -208,6 +161,7 @@ services:
 ```
 
 if you only want to stop the `phpmyadmin` service, you can run 
+
 ```console 
 $ docker compose down phpmyadmin
 ``` 

content/manuals/compose/how-tos/project-name.md

@@ -1,20 +1,20 @@
 ---
 title: Specify a project name
 weight: 10
-description: Understand the different ways you can set a project name in Compose and what the precedence is.
+description: Learn how to set a custom project name in Compose and understand the precedence of each method.
 keywords: name, compose, project, -p flag, name top-level element
 aliases:
 - /compose/project-name/
 ---
 
-In Compose, the default project name is derived from the base name of the project directory. However, you have the flexibility to set a custom project name. 
+By default, Compose assigns the project name based on the name of the directory that contains the Compose file. You can override this with several methods.
 
 This page offers examples of scenarios where custom project names can be helpful, outlines the various methods to set a project name, and provides the order of precedence for each approach.
 
 > [!NOTE]
 >
 > The default project directory is the base directory of the Compose file. A custom value can also be set
-> for it using the [`--project-directory` command line option](/reference/cli/docker/compose.md#use--p-to-specify-a-project-name).
+> for it using the [`--project-directory` command line option](/reference/cli/docker/compose.md#options).
 
 ## Example use cases
 

content/manuals/compose/how-tos/startup-order.md

@@ -1,6 +1,6 @@
 ---
-description: How to control service startup and shutdown order in Docker Compose
-keywords: documentation, docs, docker, compose, startup, shutdown, order
+description: Learn how to manage service startup and shutdown order in Docker Compose using depends_on and healthchecks.
+keywords: docker compose startup order, compose shutdown order, depends_on, service healthcheck, control service dependencies
 title: Control startup and shutdown order in Compose
 linkTitle: Control startup order
 weight: 30
@@ -13,7 +13,7 @@ You can control the order of service startup and shutdown with the
 containers in dependency order, where dependencies are determined by
 `depends_on`, `links`, `volumes_from`, and `network_mode: "service:..."`.
 
-A good example of when you might use this is an application which needs to access a database. If both services are started with `docker compose up`, there is a chance this will fail since the application service might start before the database service and won't find a database able to handle its SQL statements. 
+For example, if your application needs to access a database and both services are started with `docker compose up`, there is a chance this will fail since the application service might start before the database service and won't find a database able to handle its SQL statements. 
 
 ## Control startup