From 6bedc196cc74730522123e159d3e49f411b5c3cd Mon Sep 17 00:00:00 2001
From: Guillaume Lours <705411+glours@users.noreply.github.com>
Date: Tue, 21 Mar 2023 17:41:50 +0100
Subject: [PATCH] update -p project name flag documentation

Signed-off-by: Guillaume Lours <705411+glours@users.noreply.github.com>
---
 docs/reference/compose.md          | 19 +++++++++++++------
 docs/reference/docker_compose.yaml | 19 +++++++++++++------
 2 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/docs/reference/compose.md b/docs/reference/compose.md
index 46abdf0761..94cee4e02b 100644
--- a/docs/reference/compose.md
+++ b/docs/reference/compose.md
@@ -115,12 +115,19 @@ $ docker compose -f ~/sandbox/rails/compose.yaml pull db
 
 ### Use `-p` to specify a project name
 
-Each configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t
-specify the flag, Compose uses the current directory name.
-Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable.
-
-Many Compose subcommands can be run without a Compose file by passing
-the project name.
+Each configuration has a project name. Compose sets the project name using
+the following mechanisms, in order of precedence:
+- The `-p` command line flag
+- The `COMPOSE_PROJECT_NAME` environment variable
+- The top level `name:` variable from the config file (or the last `name:`
+from a series of config files specified using `-f`)
+- The `basename` of the project directory containing the config file (or
+containing the first config file specified using `-f`)
+- The `basename` of the current directory if no config file is specified
+Project names must contain only lowercase letters, decimal digits, dashes,
+and underscores, and must begin with a lowercase letter or decimal digit. If
+the `basename` of the project directory or current directory violates this
+constraint, you must use one of the other mechanisms.
 
 ```console
 $ docker compose -p my_project ps -a
diff --git a/docs/reference/docker_compose.yaml b/docs/reference/docker_compose.yaml
index dcd3692bce..16b3d3fd9d 100644
--- a/docs/reference/docker_compose.yaml
+++ b/docs/reference/docker_compose.yaml
@@ -63,12 +63,19 @@ long: |-
 
     ### Use `-p` to specify a project name
 
-    Each configuration has a project name. If you supply a `-p` flag, you can specify a project name. If you don’t
-    specify the flag, Compose uses the current directory name.
-    Project name can also be set by `COMPOSE_PROJECT_NAME` environment variable.
-
-    Many Compose subcommands can be run without a Compose file by passing
-    the project name.
+    Each configuration has a project name. Compose sets the project name using
+    the following mechanisms, in order of precedence:
+    - The `-p` command line flag
+    - The `COMPOSE_PROJECT_NAME` environment variable
+    - The top level `name:` variable from the config file (or the last `name:`
+    from a series of config files specified using `-f`)
+    - The `basename` of the project directory containing the config file (or
+    containing the first config file specified using `-f`)
+    - The `basename` of the current directory if no config file is specified
+    Project names must contain only lowercase letters, decimal digits, dashes,
+    and underscores, and must begin with a lowercase letter or decimal digit. If
+    the `basename` of the project directory or current directory violates this
+    constraint, you must use one of the other mechanisms.
 
     ```console
     $ docker compose -p my_project ps -a