Improve documentation on the behaviour of update and install

[chernals]

I believe that the documentation could be improved regarding what update and install are doing.

To me it is not really clear, for example:

• when doing update are the new packages installed? is the pyproject.toml file update with latest version numbers?
• when should one do install ? Only the first time?

Maybe we could collect here answers to questions like the two above and I'll be happy to make a PR for the doc.

[finswimmer]

The purpose of poetry install is to:

• create a venv if None exists
• resolve dependency and write the exact version to poetry.lock if None exists
• install the locked dependencies in the venv
• install the current project in editable mode

A poetry install is only necessary if you:

• create the venv the first time
• change any metadata of the project, like version number
• add "scripts" entry points to the pyproject.toml

The purpose of poetry update is to:

• update all dependencies to the current version within in the pyproject.toml specified version range
• write the updated version to poetry.lock
• the version numbers in pyproject.toml remain untouched

[chernals]

Thanks !

How does poetry update behave when "extra" dependencies are declared or with respect to development dependencies? Does it follow what poetry install did when last executed? (for example if poetry install --no-dev then poetry update will not touch the developement dependencies, if poetry install (without -E foo0 then poetry update will not touch the foo extra dependencies?

[mrkeuz]

Same issue with poetry install . Always confused with this command help.

Help also should explain:

• where dependencies will be installed - exactly into virtual environment (even poetry shell virtual env not activated). Not to system python dependencies. Even poetry shell / virtual env not activated. While virtualenvs.create = true

I understand now that it assumed and expected but not clear from docs. At first, I have trying to install packages into system via poetry install. Exactly because not well documented.

[rafrafek]

Are dev (or other groups) dependencies installed by default?

[neersighted]

Are dev (or other groups) dependencies installed by default?

The best intro to the feature is the release announcement which goes into detail with examples. Yes, they are installed by default using Poetry (but not captured by tools that build/install as a Python package).

[rafrafek]

Yes, they are installed by default using Poetry (but not captured by tools that build/install as a Python package).

Can we add this information to the docs here: https://python-poetry.org/docs/cli/#install

[neersighted]

PRs welcome :)