docs: 📝 Decision post on why to use poetry

Closes #4

Author: lwjohnst86

why-poetry.qmd

@@ -0,0 +1,97 @@
+---
+title: "Why Poetry"
+description: "Our reasons for using Poetry for managing Python package dependencies when building Django and Python projects."
+author: "Luke W. Johnston"
+date: last-modified
+categories:
+- package dependencies
+- virtual environments
+- python
+---
+
+## Context and Problem Statement
+
+Managing the packages we depend on (e.g. Django) in Python isn't "simply" installing it on your computer. The issue with installing Python packages on your computer is dependency conflicts that occur, where the "dependency trees" of one package require a different dependency tree than another one. So installing a package that requires a specific version of one package, while another package you already have installed requires another version can cause system problems.
+
+The solution to this problem is by using "virtual environments" in Python. These are environments that are separate from the rest of the system and can install any packages without impacting other environments.
+
+The problem is that there multiple ways of creating these virtual environments and managing package dependencies.
+
+## Decision Drivers
+
+- Package dependency management is a critical task, so we need a tool for it.
+- Ensuring we have some way of building our Python projects in a way that is less likely to be a "it works on my computer" issue.
+
+## Considered Options
+
+There are (unfortunately) multiple tools to manage package dependencies in Python, for example, listed [here](https://packaging.python.org/en/latest/tutorials/managing-dependencies/#other-tools-for-application-dependency-management) and [here](https://python.libhunt.com/poetry-alternatives). There are also comparison sites like [this](https://ritza.co/articles/gen-articles/pipenv-vs-virtualenv-vs-poetry-vs-pyenv-vs-pip/), [this](https://www.warp.dev/blog/prose-about-poetry), [this](https://dev.to/adamghill/python-package-manager-comparison-1g98), and [this](https://dev.to/frostming/a-review-pipenv-vs-poetry-vs-pdm-39b4) that go into more detail about many of these tools, as well as some descriptive statistics of the popularities of each [here](https://python.libhunt.com/poetry-alternatives).
+
+We'll only cover:
+
+- [Pipenv](https://pipenv.pypa.io/en/latest/index.html)
+- [Poetry](https://python-poetry.org/)
+- [Hatch](https://hatch.pypa.io/latest/version/)
+- [PDM](https://pdm-project.org/latest/usage/dependency/)
+
+### Pipenv
+
+Was designed to combine the functionality of `pip` and `virtualenv`.
+
+- **Pros**:
+    - Fairly popular
+    - Has been around for a while
+    - Only handles package dependencies (no other features)
+- **Cons**:
+    - The design is a bit older and not as intuitive/clear to use
+    - The documentation is a bit too verbose/technical
+    - The package caching doesn't seem to be well designed/robust, so packages could get unnecessarily re-installed
+    - Only handles package dependency management, which means we need another tool to develop software (like a Python package)
+
+### Poetry
+
+- **Pros**:
+    - Popular and widely used
+    - Very well designed website and documentation
+    - Handles package dependencies with lock files (detailed list of packages and versioning)
+    - Can set up and help manage a Python project (e.g. Python package)
+    - Designed from the ground up to consider the needs of package development and dependency resolution
+    - Allows for external plug-ins for further customization
+    - Similar dependency management to other languages
+    - Installable with `pipx`
+- **Cons**:
+    - Installation and resolving package dependency trees (so there are no conflicts) can be a bit slow
+    - Not completely PEP compliant (not yet support [PEP 621](https://peps.python.org/pep-0621/), but an Issue on it is [here](https://github.com/python-poetry/roadmap/issues/3)), though this isn't a critical problem
+
+### Hatch
+
+- **Pros**:
+    - Very similar to Poetry
+    - Is fully PEP-compliant
+    - Is relatively new, and may be the better option in the future
+    - Is very opinionated
+    - Good documentation
+    - Now maintained under the official PyPA
+- **Cons**:
+    - Is very opinionated
+    - Is relatively new, so might still be working through things
+    - Not as widely used compared to the others
+
+### PDM
+
+- **Pros**:
+    - Fully PEP-compliant
+    - Decent documentation
+- **Cons**:
+    - Relatively new
+    - Not as widely used or as popular
+    - Doesn't have distribution specific installation builds (need to use `curl` to install, which isn't the most secure way of installing)
+    - Can't install through `pipx`
+
+## Decision Outcome
+
+We decided on Poetry because it has amazing documentation, is well designed, and is very popular and widely used.
+
+### Consequences
+
+- Because it isn't fully PEP compliant, we might encounter some issues
+- Doesn't have the "official" support that Hatch has, so we might reconsider the decision to use Poetry at a future date