Explain whether to commit poetry.lock (#7506)

Co-authored-by: Randy Döring <30527984+radoering@users.noreply.github.com>

docs/basic-usage.md

@@ -219,7 +219,11 @@ but they may not all be at the very latest available versions
 (some dependencies listed in the `poetry.lock` file may have released newer versions since the file was created).
 (some dependencies listed in the `poetry.lock` file may have released newer versions since the file was created).
 This is by design, it ensures that your project does not break because of unexpected changes in dependencies.
 This is by design, it ensures that your project does not break because of unexpected changes in dependencies.
 
 
-### Commit your `poetry.lock` file to version control
+### Committing your `poetry.lock` file to version control
+
+#### As an application developer
+
+Application developers commit `poetry.lock` to get more reproducible builds.
 
 
 Committing this file to VC is important because it will cause anyone who sets up the project
 Committing this file to VC is important because it will cause anyone who sets up the project
 to use the exact same versions of the dependencies that you are using.
 to use the exact same versions of the dependencies that you are using.
@@ -230,9 +234,15 @@ Even if you develop alone, in six months when reinstalling the project you can f
 the dependencies installed are still working even if your dependencies released many new versions since then.
 the dependencies installed are still working even if your dependencies released many new versions since then.
 (See note below about using the update command.)
 (See note below about using the update command.)
 
 
-{{% note %}}
-For libraries it is not necessary to commit the lock file.
-{{% /note %}}
+#### As a library developer
+
+Library developers have more to consider. Your users are application developers, and your library will run in a Python environment you don't control.
+
+The application ignores your library's lock file. It can use whatever dependency version meets the constraints in your `pyproject.toml`. The application will probably use the latest compatible dependency version. If your library's `poetry.lock` falls behind some new dependency version that breaks things for your users, you're likely to be the last to find out about it.
+
+A simple way to avoid such a scenario is to omit the `poetry.lock` file. However, by doing so, you sacrifice reproducibility and performance to a certain extent. Without a lockfile, it can be difficult to find the reason for failing tests, because in addition to obvious code changes an unnoticed library update might be the culprit. Further, Poetry will have to lock before installing a dependency if `poetry.lock` has been omitted. Depending on the number of dependencies, locking may take a significant amount of time.
+
+If you do not want to give up the reproducibility and performance benefits, consider a regular refresh of `poetry.lock` to stay up-to-date and reduce the risk of sudden breakage for users.
 
 
 ### Installing dependencies only
 ### Installing dependencies only