mirror of
https://github.com/TagStudioDev/TagStudio.git
synced 2026-01-28 22:01:24 +00:00
refactor!: change layout; import and build change
Fixes: #200 Fixes: #365 Fixes: #512 Fixes: #800 fix(pyproject): resolve mix-up of mypy and pytest chore(ci): remove legacy scripts chore: format with new mypy rules; fix translation test wip(ci/mypy): remove config flag fix(pyinstaller): use correct dict access fix(resources): usage in ts_qt.py feat(nix/package): validate tests with pytest hook fix(nix/package): remove old dependency patch feat(nix): support Darwin fix(nix/package): move check deps to checkInputs fix(nix/shell): typo fix(nix/shell): correctly wrap Python with Qt args fix(pyproject): specify mypy-extensions feat(nix/package): provide pillow-jxl-plugin nix(nix/package): split into multiple files, allow overriding of JXL and vtf2img fix(nix/shell): provide FFmpeg on runtime feat(flake): output pillow-jxl-plugin and vtf2img fix(nix/package): load pipewire feat(nix/package): run tests on pillow-jxl-plugin fix: remove extra noqa comment docs: update installation docs docs: shrink table size on docs site nit(nix/package): pipewire not needed in buildInputs docs: update commands, environment, setup fix: use consistent possessives chore: format with prettier, add ignore flags fix(pyinstaller): consume from pyproject Revert "fix(pyinstaller): consume from pyproject" This reverts commit 398cd4e5630a3e83d22d15286d7ac59b4c07c5d6. refactor: use icon from resource manager Also fixes incorrect path currently used in ts_qt.py. nix(pyinstaller): replace use of sys.platform with platform.system docs: add build section Co-authored-by: Travis Abendshien <46939827+CyanVoxel@users.noreply.github.com>
This commit is contained in:
Xarvex
@@ -1,100 +1,56 @@
|
||||
# Contributing to TagStudio
|
||||
|
||||
_Last Updated: January 30th, 2025_
|
||||
_Last Updated: March 8th, 2025_
|
||||
|
||||
Thank you so much for showing interest in contributing to TagStudio! Here are a set of instructions and guidelines for contributing code or documentation to the project. This document will change over time, so make sure that your contributions still line up with the requirements here before submitting a pull request.
|
||||
|
||||
## Getting Started
|
||||
|
||||
- Check the [Feature Roadmap](/docs/updates/roadmap.md) page to see what priority features there are, the [FAQ](/README.md/#faq), as well as the open [Issues](https://github.com/TagStudioDev/TagStudio/issues) and [Pull Requests](https://github.com/TagStudioDev/TagStudio/pulls).
|
||||
- Check the [Feature Roadmap](/docs/updates/roadmap.md) page to see what priority features there are, the [FAQ](/README.md/#faq), as well as the project's [Issues](https://github.com/TagStudioDev/TagStudio/issues) and [Pull Requests](https://github.com/TagStudioDev/TagStudio/pulls).
|
||||
- If you'd like to add a feature that isn't on the feature roadmap or doesn't have an open issue, **PLEASE create a feature request** issue for it discussing your intentions so any feedback or important information can be given by the team first.
|
||||
- We don't want you wasting time developing a feature or making a change that can't/won't be added for any reason ranging from pre-existing refactors to design philosophy differences.
|
||||
- **Please don't** create pull requests that consist of large refactors, _especially_ without discussing them with us first. These end up doing more harm than good for the project by continuously delaying progress and disrupting everyone else's work.
|
||||
- If you wish to discuss TagStudio further, feel free to join the [Discord Server](https://discord.com/invite/hRNnVKhF2G)
|
||||
- If you wish to discuss TagStudio further, feel free to join the [Discord Server](https://discord.com/invite/hRNnVKhF2G)!
|
||||
|
||||
### Contribution Checklist
|
||||
|
||||
- I've read the [Feature Roadmap](/docs/updates/roadmap.md) page
|
||||
- I've read the [FAQ](/README.md/#faq), including the "[Features I Likely Won't Add/Pull](/README.md/#features-i-likely-wont-addpull)" section
|
||||
- I've checked the open [Issues](https://github.com/TagStudioDev/TagStudio/issues) and [Pull Requests](https://github.com/TagStudioDev/TagStudio/pulls)
|
||||
- I've checked the project's [Issues](https://github.com/TagStudioDev/TagStudio/issues) and [Pull Requests](https://github.com/TagStudioDev/TagStudio/pulls)
|
||||
- **I've created a new issue for my feature/fix _before_ starting work on it**, or have at least notified others in the relevant existing issue(s) of my intention to work on it
|
||||
- I've set up my development environment including Ruff, Mypy, and PyTest
|
||||
- I've read the [Code Guidelines](#code-guidelines) and/or [Documentation Guidelines](#documentation-guidelines)
|
||||
- **_I mean it, I've found or created an issue for my feature/fix!_**
|
||||
|
||||
> [!NOTE]
|
||||
> If the fix is small and self-explanatory (i.e. a typo), then it doesn't require an issue to be opened first. Issue tracking is supposed to make our lives easier, not harder. Please use your best judgement to minimize the amount of work involved for everyone involved.
|
||||
> If the fix is small and self-explanatory (i.e. a typo), then it doesn't require an issue to be opened first. Issue tracking is supposed to make our lives easier, not harder. Please use your best judgement to minimize the amount of work for everyone involved.
|
||||
|
||||
## Creating a Development Environment
|
||||
|
||||
### Prerequisites
|
||||
If you wish to develop for TagStudio, you'll need to create a development environment by installing the required dependencies. You have a number of options depending on your level of experience and familiarly with existing Python toolchains.
|
||||
|
||||
- [Python](https://www.python.org/downloads/) 3.12
|
||||
- [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`)
|
||||
If you know what you're doing and have developed for Python projects in the past, you can get started quickly with the "Brief Instructions" below. Otherwise, please see the full instructions on the documentation website for "[Creating a Development Environment](https://docs.tagstud.io/install/#creating-a-development-environment)".
|
||||
|
||||
### Creating a Python Virtual Environment
|
||||
### Brief Instructions
|
||||
|
||||
If you wish to launch the source version of TagStudio outside of your IDE:
|
||||
1. Have [Python 3.12](https://www.python.org/downloads/) and PIP installed. Also have [FFmpeg](https://ffmpeg.org/download.html) installed if you wish to have audio/video playback and thumbnails.
|
||||
2. Clone the repository to the folder of your choosing:
|
||||
```
|
||||
git clone https://github.com/TagStudioDev/TagStudio.git
|
||||
```
|
||||
3. Use a dependency manager such as [uv](https://docs.astral.sh/uv/) or [Poetry 2.0](https://python-poetry.org/blog/category/releases/) to install the required dependencies, or alternatively create and activate a [virtual environment](https://docs.tagstud.io/install/#manual-installation) with `venv`.
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Depending on your system, Python may be called `python`, `py`, `python3`, or `py3`. These instructions use the alias `python3` for consistency. You can check to see which alias your system uses and if it's for the correct Python version by typing `python3 --version` (or whichever alias) into your terminal.
|
||||
4. If using a virtual environment instead of a dependency manager, install an editable version of the program and development dependencies with the following PIP command:
|
||||
|
||||
> [!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._
|
||||
```
|
||||
pip install -e .[dev]
|
||||
```
|
||||
|
||||
1. Make sure you're using the correct Python version:
|
||||
- If the output matches `Python 3.12.x` (where the x is any number) then you're using the correct Python version and can skip to step 2. Otherwise, you can install the correct Python version from the [Python](https://www.python.org/downloads/) website, or you can use a tool like [pyenv](https://github.com/pyenv/pyenv/) to install the correct version without changes to your system:
|
||||
1. Follow pyenv's [install instructions](https://github.com/pyenv/pyenv/?tab=readme-ov-file#installation) for your system.
|
||||
2. Install the appropriate Python version with pyenv by running `pyenv install 3.12` (This will **not** mess with your existing Python installation).
|
||||
3. Navigate to the repository root folder in your terminal and run `pyenv local 3.12`.
|
||||
- You could alternatively use `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, however using `local` is recommended.
|
||||
Otherwise, modify the command above for use with your dependency manager of choice. For example if using uv, you may use this:
|
||||
|
||||
2. In the root repository directory, create a python virtual environment:
|
||||
`python3 -m venv .venv`
|
||||
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`
|
||||
Depending on your system, the regular activation script *might* not work on alternative shells. In this case, refer to the table below for supported shells:
|
||||
|Shell |Script |
|
||||
|-------:|:------------------------|
|
||||
|Bash/ZSH|`.venv/bin/activate` |
|
||||
|Fish |`.venv/bin/activate.fish`|
|
||||
|CSH/TCSH|`.venv/bin/activate.csh` |
|
||||
|PWSH |`.venv/bin/activate.ps1` |
|
||||
|
||||
|
||||
4. Install the required packages:
|
||||
|
||||
- `pip install -r requirements.txt`
|
||||
- If developing (includes Ruff and Mypy): `pip install -r requirements-dev.txt`
|
||||
|
||||
_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)
|
||||
|
||||
- To launch TagStudio, launch the `start_win.bat` file. You can modify this .bat file or create a shortcut and add one or more additional arguments if desired.
|
||||
|
||||
- **Linux/macOS** (TagStudio.sh)
|
||||
|
||||
- Run the "TagStudio.sh" script and the program should launch! (Make sure that the script is marked as executable if on Linux). Note that launching from the script from outside of a terminal will not launch a terminal window with any debug or crash information. If you wish to see this information, just launch the shell script directly from your terminal with `./TagStudio.sh`.
|
||||
|
||||
- **NixOS** (Nix Flake)
|
||||
- Use the provided [Flake](https://nixos.wiki/wiki/Flakes) to create and enter a working environment by running `nix develop`. Then, run the program via `python3 tagstudio/tag_studio.py` from the root directory.
|
||||
|
||||
> [!WARNING]
|
||||
> Support for NixOS is still a work in progress.
|
||||
|
||||
- **Any** (No Scripts)
|
||||
|
||||
- Alternatively, with the virtual environment loaded, run the python file at `tagstudio\tag_studio.py` from your terminal. If you're in the project's root directory, simply run `python3 tagstudio/tag_studio.py`.
|
||||
```
|
||||
uv pip install -e .[dev]
|
||||
```
|
||||
|
||||
## Workflow Checks
|
||||
|
||||
@@ -125,16 +81,16 @@ Mypy is a static type checker for Python. It sure has a lot to say sometimes, bu
|
||||
|
||||
#### Running Locally
|
||||
|
||||
- **First time only:** Move into the `/tagstudio` directory with `cd tagstudio` and run the following:
|
||||
- **(First time only)** Run the following:
|
||||
- `mkdir -p .mypy_cache`
|
||||
- `mypy --install-types --non-interactive`
|
||||
- Check code by moving into the `/tagstudio` directory with `cd tagstudio` _(if you aren't already inside)_ and running `mypy --config-file ../pyproject.toml .`. _(Don't forget the `.` at the end!)_
|
||||
- You can now check code by running `mypy --config-file pyproject.toml .` in the repository root. _(Don't forget the "." at the end!)_
|
||||
|
||||
Mypy is also available as a VS Code [extension](https://marketplace.visualstudio.com/items?itemName=matangover.mypy), PyCharm [plugin](https://plugins.jetbrains.com/plugin/11086-mypy), and [more](https://plugins.jetbrains.com/plugin/11086-mypy).
|
||||
|
||||
### PyTest
|
||||
|
||||
- Run all tests by moving into the `/tagstudio` directory with `cd tagstudio` and running `pytest tests/`.
|
||||
- Run all tests by running `pytest tests/` in the repository root.
|
||||
|
||||
## Code Style
|
||||
|
||||
@@ -173,7 +129,7 @@ Most of the style guidelines can be checked, fixed, and enforced via Ruff. Older
|
||||
> [!IMPORTANT]
|
||||
> Please do not force push if your PR is open for review!
|
||||
>
|
||||
> Force pushing makes it impossible to discern which changes have already been reviewed and which haven't. This means a reviewer will then have to rereview all the already reviewed code, which is a lot of unnecessary work for reviewers.
|
||||
> Force pushing makes it impossible to discern which changes have already been reviewed and which haven't. This means a reviewer will then have to re-review all the already reviewed code, which is a lot of unnecessary work for reviewers.
|
||||
|
||||
> [!TIP]
|
||||
> If you're unsure where to stop the scope of your PR, ask yourself: _"If I broke this up, could any parts of it still be used by the project in the meantime?"_
|
||||
@@ -182,7 +138,7 @@ Most of the style guidelines can be checked, fixed, and enforced via Ruff. Older
|
||||
|
||||
- Final code must function on supported versions of Windows, macOS, and Linux:
|
||||
- Windows: 10, 11
|
||||
- macOS: 12.0+
|
||||
- macOS: 13.0+
|
||||
- Linux: _Varies_
|
||||
- Final code must **_NOT:_**
|
||||
- Contain superfluous or unnecessary logging statements
|
||||
|
||||
Reference in New Issue
Block a user