mirror of
https://github.com/TagStudioDev/TagStudio.git
synced 2026-01-29 06:10:51 +00:00
docs: refer to pyenv in CONTRIBUTING.md
This commit was made in order to account for users who may already have
a Python installation that isn't 3.12.
A good real world scenario where this may be a problem is users running
on rolling release Linux distributions, such as Arch Linux which
provides bleeding edge updates in a weekly basis.
Continuing with Arch Linux as an example, it provides Python 3.13, which
the current version of TagStudio doesn't seem to work with, an issue I
encountered myself this morning.
In some systems like Windows, this may not matter, but it is an issue
nonetheless, and users using a package manager centric system can't be
expected to downgrade/upgrade their Python version for TagStudio, as
this may cause issues in their system.
The easiest way to solve this is with pyenv, which enables users to
install other Python versions independent from each other, aside from
the system install, and allows specifying a version to use for a
directory (And its subdirectories), the current terminal session, or the
entire system if desired.
Here is a short, technical and objective summary of the changes:
- Updated `.gitignore` to to ignore `.python-version` which pyenv uses.
- Updated CONTRIBUTING.md to refer to pyenv for versioning issues.
- pyenv is listed as a prerequisite, specifying in parenthesis that it's only for when your Python install isn't 3.12.
- The "Creating a Python Virtual Environment" section now has an additional step at the beginning, to check that the current Python installation is 3.12.
- As part of this added step, there are steps to use pyenv to install Python 3.12 separately from the existing Python installation, and activate it for the TagStudio root folder, in case it's not the appropriate version.
- The numbering of the other steps was offset accordingly.
- The "Manually Launching (Outside of an IDE)" section now refers to the above first step, should the user encounter some kind of error.
This commit is contained in:
4
.gitignore
vendored
4
.gitignore
vendored
@@ -88,9 +88,7 @@ profile_default/
|
||||
ipython_config.py
|
||||
|
||||
# pyenv
|
||||
# For a library or package, you might want to ignore these files since the code is
|
||||
# intended to run in multiple environments; otherwise, check them in:
|
||||
# .python-version
|
||||
.python-version
|
||||
|
||||
# pipenv
|
||||
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
||||
|
||||
@@ -35,6 +35,7 @@ Thank you so much for showing interest in contributing to TagStudio! Here are a
|
||||
### Prerequisites
|
||||
|
||||
- [Python](https://www.python.org/downloads/) 3.12
|
||||
- [pyenv](https://github.com/pyenv/pyenv/) (If your system install of Python isn't 3.12 but you don't wish to upgrade/downgrade, otherwise ignore this.)
|
||||
- [Ruff](https://github.com/astral-sh/ruff) (Included in `requirements-dev.txt`)
|
||||
- [Mypy](https://github.com/python/mypy) (Included in `requirements-dev.txt`)
|
||||
- [PyTest](https://docs.pytest.org) (Included in `requirements-dev.txt`)
|
||||
@@ -49,15 +50,24 @@ If you wish to launch the source version of TagStudio outside of your IDE:
|
||||
> [!TIP]
|
||||
> On Linux and macOS, you can launch the `tagstudio.sh` script to skip the following process, minus the `requirements-dev.txt` installation step. _Using the script is fine if you just want to launch the program from source._
|
||||
|
||||
1. In the root repository directory, create a python virtual environment:
|
||||
1. Make sure you're using the correct Python version:
|
||||
`python3 --version` (As described above)
|
||||
- If the output matches `Python 3.12.x` where the x is any number representing a patch update (Does not matter), then continue to step 2 and ignore the info below about pyenv, you won't need to install it either.
|
||||
- Otherwise, you probably want to use pyenv so you don't have to downgrade or upgrade your Python installation before continuing to step 2:
|
||||
1. Follow the install instructions for your system on [the pyenv Github repository](https://github.com/pyenv/pyenv/).
|
||||
2. Install the appropriate Python version with pyenv by running `pyenv install 3.12` (This will **not** mess with your existing Python install in any way).
|
||||
3. Go into the root of this repository with a terminal, and run `pyenv local 3.12` to tell pyenv that Python 3.12 should be used in this folder (This will **not** mess with your existing Python install either, it only applies to this folder).
|
||||
- You can also do `pyenv shell 3.12` or `pyenv global 3.12` instead to set the Python version for the current terminal session or the entire system respectively, but `local` is recommended.
|
||||
|
||||
2. In the root repository directory, create a python virtual environment:
|
||||
`python3 -m venv .venv`
|
||||
2. Activate your environment:
|
||||
3. Activate your environment:
|
||||
|
||||
- Windows w/Powershell: `.venv\Scripts\Activate.ps1`
|
||||
- Windows w/Command Prompt: `.venv\Scripts\activate.bat`
|
||||
- Linux/macOS: `source .venv/bin/activate`
|
||||
|
||||
3. Install the required packages:
|
||||
4. Install the required packages:
|
||||
|
||||
- `pip install -r requirements.txt`
|
||||
- If developing (includes Ruff and Mypy): `pip install -r requirements-dev.txt`
|
||||
@@ -65,6 +75,7 @@ If you wish to launch the source version of TagStudio outside of your IDE:
|
||||
_Learn more about setting up a virtual environment [here](https://docs.python.org/3/tutorial/venv.html)._
|
||||
|
||||
### Manually Launching (Outside of an IDE)
|
||||
#### If you encounter errors about the Python version, or seemingly vague script errors, [pyenv](https://github.com/pyenv/pyenv/) may solve your issue, see step 1 of [Creating a Python Virtual Environment](#creating-a-python-virtual-environment)
|
||||
|
||||
- **Windows** (start_win.bat)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user