Explain FORCE_COLOR: 3 (#410)

* Explain FORCE_COLOR: 3

* style: pre-commit fixes

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: danielballan

.github/workflows/reusable-cookie.yml

@@ -4,6 +4,8 @@ on:
   workflow_call:
 
 env:
+  # Many color libraries just need this to be set to any value, but at least
+  # one distinguishes color depth, where "3" -> "256-bit color".
   FORCE_COLOR: 3
 
 jobs:

.github/workflows/reusable-rr-tests.yml

@@ -4,6 +4,8 @@ on:
   workflow_call:
 
 env:
+  # Many color libraries just need this to be set to any value, but at least
+  # one distinguishes color depth, where "3" -> "256-bit color".
   FORCE_COLOR: 3
 
 jobs:

docs/pages/guides/tasks.md

@@ -80,8 +80,8 @@ action:
 
 You can now access all current versions of Python from nox. At least in GitHub
 Actions, you should add `--forcecolor` to your nox runs to get color output in
-your logs, or set `env: FORCE_COLOR: 3`. If you'd like to customize the versions
-of Python prepared for you, then use input like this:
+your logs, or set `env: FORCE_COLOR: 3`[^force_color]. If you'd like to
+customize the versions of Python prepared for you, then use input like this:
 
 ```yaml
 - uses: wntrblm/nox@2024.03.02
@@ -371,3 +371,9 @@ using nox include [pip](https://github.com/pypa/pip/blob/main/noxfile.py),
 [manylinux](https://github.com/pypa/manylinux/blob/main/noxfile.py),
 [packaging](https://github.com/pypa/packaging/blob/main/noxfile.py), and
 [packaging.python.org](https://github.com/pypa/packaging.python.org/blob/main/noxfile.py).
+
+[^force_color]:
+    Many color libraries just need `FORCE_COLOR` to be set to any value, but at
+    least [one](https://pypi.org/project/plumbum/) distinguishes color depth,
+    where "3" -> "256-bit color". For many use cases, using `FORCE_COLOR: 1` is
+    fine.

{{cookiecutter.project_name}}/.github/workflows/ci.yml

@@ -12,6 +12,8 @@ concurrency:
   cancel-in-progress: true
 
 env:
+  # Many color libraries just need this to be set to any value, but at least
+  # one distinguishes color depth, where "3" -> "256-bit color".
   FORCE_COLOR: 3
 
 jobs:

{{cookiecutter.project_name}}/.github/workflows/{% if cookiecutter.__type!='compiled' %}cd.yml{% endif %}

@@ -15,6 +15,8 @@ concurrency:
   cancel-in-progress: true
 
 env:
+  # Many color libraries just need this to be set to any value, but at least
+  # one distinguishes color depth, where "3" -> "256-bit color".
   FORCE_COLOR: 3
 
 jobs:

{{cookiecutter.project_name}}/.github/workflows/{% if cookiecutter.__type=='compiled' %}cd.yml{% endif %}

@@ -11,6 +11,8 @@ concurrency:
   cancel-in-progress: true
 
 env:
+  # Many color libraries just need this to be set to any value, but at least
+  # one distinguishes color depth, where "3" -> "256-bit color".
   FORCE_COLOR: 3
 
 jobs: