Stop Environments from Breaking

[Unobtainiumrock]

Outline & Motivation

The proposal is simple and relatively straightforward. I've wasted countless hours wiping away my environment because of these details that were hidden from me.

Short Version

1. Change the virtual environment management level from global to the project directory level
2. Add the .venv to .gitignore

Longer Version With Justifications

Proposal: Use In-Project Virtual Environments for a Cleaner Development Workflow

Context:
Currently, our contribution guide instructs developers to set up the Poetry environment with:

• poetry install
• poetry shell
• pre-commit install

However, these instructions assume that the virtual environment is managed globally in ~/.cache/pypoetry/virtualenvs/. In practice, this can lead to issues where stale or corrupted environments affect the development process, especially during the frequent rebuilds common in our dev cycle.

Proposal:
To avoid these pitfalls, I propose that we configure Poetry to always create a virtual environment inside the project directory by adding the following step to the contribution guide:

poetry config virtualenvs.in-project true

This change offers several benefits:

• Local Control: The virtual environment will reside in a .venv folder at the project root. This makes it easier to delete, recreate, or inspect if issues arise.
• Consistency: Developers can be sure they’re always working with a fresh environment that's tied directly to the project state, rather than one cached in the global Poetry directory.
• Simpler Cleanup: If something goes wrong, deleting the .venv folder and rerunning poetry install is straightforward.

Implementation Details:

1. Update the Contribution Guide:

   • After instructing contributors to install Poetry, add a step:

     poetry config virtualenvs.in-project true

   • Continue with poetry install, poetry shell, and pre-commit install as usual.

2. Add .venv to .gitignore:

   • Update the .gitignore file to include the .venv folder. This ensures that no one accidentally commits their local environment:

     .venv/
     

Example Updated Contribution Steps:

1. Install Poetry (if you haven’t already):

   pip install poetry

2. Configure Poetry to use an in-project virtual environment:

   poetry config virtualenvs.in-project true

3. Install Dependencies:

   poetry install

4. Activate the Environment:

   poetry shell

5. Install Pre-commit Hooks:

   pre-commit install

6. Proceed with your development workflow.

Conclusion:
This change will help prevent issues with stale or broken virtual environments in the global cache and streamline the setup process for contributors. I believe this small modification, along with adding .venv to .gitignore, will greatly improve the developer experience.

Pitch

No response

Additional context

No response