chore: bump version to v9.5.0 Pre-Release 1; update docs (#751)

* chore: change version branch to "Pre-Release 1"

* docs: update docstring for JSON `open_library()`

Update method docstring with exact starting and ending versions now that they exist.

* docs: update README, CONTRIBUTING.md, & index.md

* docs: update roadmap

* docs: fix typo in README, change callout

* docs: update docs site with v9.5 features

* docs: remove warning from index.md

Author: CyanVoxel

CONTRIBUTING.md

@@ -1,20 +1,15 @@
 # Contributing to TagStudio
 
-_Last Updated: December 12th, 2024_
+_Last Updated: January 30th, 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.
 
-> [!CAUTION]
-> **As of Pull Request [#332](https://github.com/TagStudioDev/TagStudio/pull/332) (SQLite Migration) the `main` branch will marked as experimental before full JSON to SQL parity is operational.** Existing TagStudio libraries are not yet compatible with this change, however they will **NOT be corrupted or deleted** if opened with these versions. Once parity is reached and a stable conversion tool in place, this notice will be removed. UPDATE: As of November 19th, 2024, full parity is rapidly approaching.
->
-> For the most recent stable feature release branch, see the [`Alpha-v9.4`](https://github.com/TagStudioDev/TagStudio/tree/Alpha-v9.4) branch. These v9.4 specific features are currently being backported to the SQL-ized `main` branch. (Feel free to help!)
-
 ## 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).
 -   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.
+-   **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)
 
 ### Contribution Checklist
@@ -141,13 +136,14 @@ Most of the style guidelines can be checked, fixed, and enforced via Ruff. Older
 
 ### Modules & Implementations
 
+-   **Do not** modify legacy library code in the `src/core/library/json/` directory
 -   Avoid direct calls to `os`
     -   Use `Pathlib` library instead of `os.path`
     -   Use `platform.system()` instead of `os.name` and `sys.platform`
 -   Don't prepend local imports with `tagstudio`, stick to `src`
 -   Use the `logger` system instead of `print` statements
 -   Avoid nested f-strings
--   Use HTML-like tags inside Qt widgets over stylesheets where possible.
+-   Use HTML-like tags inside Qt widgets over stylesheets where possible
 
 ### Commit and Pull Request Style
 
@@ -159,7 +155,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.
 
 > [!TIP]
@@ -172,9 +168,9 @@ Most of the style guidelines can be checked, fixed, and enforced via Ruff. Older
     -   macOS: 12.0+
     -   Linux: _Varies_
 -   Final code must **_NOT:_**
-    -   Contain superfluous or unnecessary logging statements.
-    -   Cause unreasonable slowdowns to the program outside of a progress-indicated task.
-    -   Cause undesirable visual glitches or artifacts on screen.
+    -   Contain superfluous or unnecessary logging statements
+    -   Cause unreasonable slowdowns to the program outside of a progress-indicated task
+    -   Cause undesirable visual glitches or artifacts on screen
 
 ## Documentation Guidelines
 

README.md

@@ -4,33 +4,15 @@ title: Home
 
 # Welcome to the TagStudio Documentation!
 
-!!! warning
-	This documentation is still a work in progress, and is intended to aide with deconstructing and understanding of the core mechanics of TagStudio and how it operates.
-
 ![TagStudio Alpha](assets/github_header.png)
 
 TagStudio is a photo & file organization application with an underlying tag-based system that focuses on giving freedom and flexibility to the user. No proprietary programs or formats, no sea of sidecar files, and no complete upheaval of your filesystem structure.
 
 <figure width="60%" markdown="span">
-  ![TagStudio screenshot](assets/screenshot.jpg)
-  <figcaption>TagStudio Alpha v9.4.2 running on Windows 10</figcaption>
+  ![TagStudio screenshot](assets/screenshot.png)
+  <figcaption>TagStudio Alpha v9.5.0 running on macOS Sequoia.</figcaption>
 </figure>
 
-## Goals
-
-- To achieve a portable, private, extensible, open-format, and feature-rich system of organizing and rediscovering files.
-- To provide powerful methods for organization, notably the concept of tag inheritance, or “taggable tags” _(and in the near future, the combination of composition-based tags)._
-- To create an implementation of such a system that is resilient against a user’s actions outside the program (modifying, moving, or renaming files) while also not burdening the user with mandatory sidecar files or requiring them to change their existing file structures and workflows.
-- To support a wide range of users spanning across different platforms, multi-user setups, and those with large (several terabyte) libraries.
-- To make the darn thing look like nice, too. It’s 2024, not 1994.
-
-## Priorities
-
-1. **The concept.** Even if TagStudio as an application fails, I’d hope that the idea lives on in a superior project. The [goals](#goals) outlined above don’t reference TagStudio once - _TagStudio_ is what references the _goals._
-2. **The system.** Frontends and implementations can vary, as they should. The core underlying metadata management system is what should be interoperable between different frontends, programs, and operating systems. A standard implementation for this should settle as development continues. This opens up the doors for improved and varied clients, integration with third-party applications, and more.
-3. **The application.** If nothing else, TagStudio the application serves as the first (and so far only) implementation for this system of metadata management. This has the responsibility of doing the idea justice and showing just what’s possible when it comes to user file management.
-4. (The name.) I think it’s fine for an app or client, but it doesn’t really make sense for a system or standard. I suppose this will evolve with time...
-
 ## Feature Roadmap
 
 The [Feature Roadmap](updates/roadmap.md) lists all of the planned core features for TagStudio to be considered "feature complete" along with estimated release milestones. The development and testing of these features takes priority over all other requested or submitted features unless they are later added to this roadmap. This helps ensure that TagStudio eventually sees a full release and becomes more usable by more people more quickly.
@@ -39,31 +21,29 @@ The [Feature Roadmap](updates/roadmap.md) lists all of the planned core features
 
 ### Libraries
 
-- Create libraries/vaults centered around a system directory. Libraries contain a series of entries: the representations of your files combined with metadata fields. Each entry represents a file in your library’s directory, and is linked to its location.
-- Address moved, deleted, or otherwise "unlinked" files by using the "Fix Unlinked Entries" option in the Tools menu.
+-   Create libraries/vaults centered around a system directory. Libraries contain a series of entries: the representations of your files combined with metadata fields. Each entry represents a file in your library’s directory, and is linked to its location.
+-   Address moved, deleted, or otherwise "unlinked" files by using the "Fix Unlinked Entries" option in the Tools menu.
 
-### Metadata + Tagging
+### Tagging + Custom Metadata
 
-- Add metadata to your library entries, including:
-  - Name, Author, Artist (Single-Line Text Fields)
-  - Description, Notes (Multiline Text Fields)
-  - Tags, Meta Tags, Content Tags (Tag Boxes)
-- Create rich tags composed of a name, a list of aliases, and a list of “parent tags” - being tags in which these tags inherit values from.
-- Copy and paste tags and fields across file entries
-- Generate tags from your existing folder structure with the "Folders to Tags" macro (NOTE: these tags do NOT sync with folders after they are created)
+-   Add custom powerful tags to your library entries
+-   Add metadata to your library entries, including:
+    -   Name, Author, Artist (Single-Line Text Fields)
+    -   Description, Notes (Multiline Text Fields)
+-   Create rich tags composed of a name, color, a list of aliases, and a list of “parent tags” - these being tags in which these tags inherit values from.
+-   Copy and paste tags and fields across file entries
+-   Automatically organize tags into groups based on parent tags marked as "categories"
+-   Generate tags from your existing folder structure with the "Folders to Tags" macro (NOTE: these tags do NOT sync with folders after they are created)
 
 ### Search
 
-- Search for entries based on tags, ~~metadata~~ (TBA), or filenames/filetypes (using `filename: <query>`).
-- Special search conditions for entries that are: `untagged` and `empty`.
+-   Search for file entries based on tags, file path (`path:`), file types (`filetype:`), and even media types! (`mediatype:`)
+-   Use and combine boolean operators (`AND`, `OR`, `NOT`) along with parentheses groups, quotation escaping, and underscore substitution to create detailed search queries
+-   Use special search conditions (`special:untagged` and `special:empty`) to find file entries without tags or fields, respectively
 
 ### File Entries
 
-- All\* file types are supported in TagStudio libraries - just not all have dedicated thumbnail support.
-- Preview most image file types, animated GIFs, videos, plain text documents, audio files\*\*, Blender projects, and more!
-- Open files or file locations by right-clicking on thumbnails and previews and selecting the respective context menu options. You can also click on the preview panel image to open the file, and click the file path label to open its location.
-- Delete files from both your library and drive by right-clicking the thumbnail(s) and selecting the "Move to Trash"/"Move to Recycle Bin" option.
-
-> _\* Weird files with no extension or files such as ".\_DS_Store" currently have limited support._
->
-> _\*\* Audio playback coming in v9.5_
+-   Nearly all file types are supported in TagStudio libraries - just not all have dedicated thumbnail support.
+-   Preview most image file types, animated GIFs, videos, plain text documents, audio files, Blender projects, and more!
+-   Open files or file locations by right-clicking on thumbnails and previews and selecting the respective context menu options. You can also click on the preview panel image to open the file, and click the file path label to open its location.
+-   Delete files from both your library and drive by right-clicking the thumbnail(s) and selecting the "Move to Trash"/"Move to Recycle Bin" option.

docs/assets/built_tag_shrek.png

@@ -2,14 +2,19 @@
 
 To download TagStudio, visit the [Releases](https://github.com/TagStudioDev/TagStudio/releases) section of the GitHub repository and download the latest release for your system under the "Assets" section. TagStudio is available for **Windows**, **macOS** _(Apple Silicon & Intel)_, and **Linux**. Windows and Linux builds are also available in portable versions if you want a more self-contained executable to move around.
 
-For video thumbnails and playback, you'll also need [FFmpeg](https://ffmpeg.org/download.html) installed on your system. 
+**We do not currently publish TagStudio to any package managers. Any TagStudio distributions outside of the GitHub releases page are _unofficial_ and not maintained by us.** Installation support will not be given to users installing from unofficial sources. Use these versions at your own risk.
+
 
 !!! info "For macOS Users"
     On macOS, you may be met with a message saying _""TagStudio" can't be opened because Apple cannot check it for malicious software."_ If you encounter this, then you'll need to go to the "Settings" app, navigate to "Privacy & Security", and scroll down to a section that says _""TagStudio" was blocked from use because it is not from an identified developer."_ Click the "Open Anyway" button to allow TagStudio to run. You should only have to do this once after downloading the application.
 
 !!! info "For Linux Users"
     On Linux with non-Qt based Desktop Environments you may be unable to open TagStudio. You need to make sure that "xcb-cursor0" or "libxcb-cursor0" packages are installed. For more info check [Missing linux dependencies](https://github.com/TagStudioDev/TagStudio/discussions/182#discussioncomment-9452896)
 
+## Third-Party Dependencies
+
+-   For video thumbnails and playback, you'll also need [FFmpeg](https://ffmpeg.org/download.html) installed on your system. If you encounter any issues with this, please reference our [FFmpeg Help](/docs/help/ffmpeg.md) guide.
+
 ## Optional Arguments
 
 Optional arguments to pass to the program:

docs/assets/github_header.png

@@ -1,26 +1,50 @@
-# Entry
+# File Entries
 
-Entries are the units that fill a [library](index.md). Each one corresponds to a file, holding a reference to it along with the metadata associated with it.
+File entries are the individual representations of your files inside a TagStudio [library](index.md). Each one corresponds one-to-one to a file on disk, and tracks all of the additional [tags](tag.md) and metadata that you attach to it inside TagStudio.
 
-### Entry Object Structure
+## Storage
 
-1. `id`
-      - Int, Unique, **Required**
-      - The ID for the Entry.
-      - Used for internal processing
-2. `filename`:
-      - String, **Required**
-      - The filename with extension of the referenced media file.
-3. `path`:
-      - String, **Required**, OS Agnostic
-      - The folder path in which the media file is located in.
-4. [`fields`](field.md):
-      - List of dicts, Optional
-      - A list of Field ID/Value dicts.
+File entry data is storied within the `ts_library.sqlite` file inside each library's `.TagStudio` folder. No modifications are made to your actual files on disk, and nothing like sidecar files are generated for your files.
 
-!!! note
-      Entries currently have several unused optional fields intended for later features.
+## Appearance
 
-## Retrieving Entries based on [Tag](tag.md) Cluster
+File entries appear as file previews both inside the thumbnail grid. The preview panel shows a more detailed preview of the file, along with extra file stats and all attached TagStudio tags and fields.
 
-By default when querying Entries, each Entry's `tags` list (stored in the form of Tag `id`s) is compared against the Tag `id`s in a given Tag cluster (list of Tag `id`s) or appended clusters in the case of multi-term queries. The type of comparison depends on the type of query and whether or not it is an inclusive or exclusive query, or a combination of both. This default searching behavior is done in _O(n)_ time, but can be sped up in the future by building indexes on certain search terms. These indexes can be stored on disk and loaded back into memory in future sessions. These indexes will also need to be updated as new Tags and Entries are added or edited.
+## Unlinked File Entries
+
+If the file that an entry is referencing has been moved, renamed, or deleted on disk, then TagStudio will display a red chain-link icon for the thumbnail image. Certain uncached stats such as the file size and image dimensions will also be unavailable to see in the preview panel when a file becomes unlinked.
+
+To fix file entries that have become unlinked, select the "Fix Unlinked Entries" option from the Tools menu. From there, refresh the unlinked entry count and choose whether to search and relink you files, and/or delete the file entires from your library. This will NOT delete or modify any files on disk.
+
+## Internal Structure
+
+-   `id` (`INTEGER`/`int`, `UNIQUE`, `NOT NULL`, `PRIMARY KEY`)
+    -   The ID for the file entry.
+    -   Used for guaranteed unique references.
+-   `folder` (`INTEGER`/`int`, `NOT NULL`, `FOREIGN KEY`)
+    -   _Not currently used, may be removed._
+-   `path` (`VARCHAR`/`Path`, `UNIQUE`, `NOT NULL`)
+    -   The filename and filepath relative to the root of the library folder.
+    -   (E.g. for library "Folder", path = "any_subfolders/filename.txt")
+-   `suffix` (`VARCHAR`/`str`, `NOT NULL`)
+    -   The filename suffix with no leading dot.
+    -   Used for quicker file extension checks.
+-   `date_created` (`DATETIME`/`Datetime`)
+    -   _Not currently used, will be implemented in an upcoming update._
+    -   The creation date of the file (not the entry).
+    -   Generates from `st_birthtime` on Windows and Mac, and `st_ctime` on Linux.
+-   `date_modified` (`DATETIME`/`Datetime`)
+    -   _Not currently used, will be implemented in an upcoming update._
+    -   The latest modification date of the file (not the entry).
+    -   Generates from `st_mtime`.
+-   `date_added` (`DATETIME`/`Datetime`)
+    -   The date the file entry was added to the TagStudio library.
+
+### Table Relationships
+
+-   `tag_entries`
+    -   A relationship between `entry_id` to `tag_id`s from the `tags` table.
+-   `text_fields`
+    -   (TODO: determine the relationship for `entry_id`)
+-   `datetime_fields`
+    -   (TODO: determine the relationship for `entry_id`)