Skip to content

Commit 0dd0616

Browse files
CyanVoxelCyanVoxel
committed
docs: update roadmap and library changes
1 parent 0380f1b commit 0dd0616

3 files changed

Lines changed: 117 additions & 101 deletions

File tree

‎docs/library-changes.md‎

Lines changed: 43 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ This page outlines the various changes made to the TagStudio library save file f
1212

1313
---
1414

15-
## JSON
15+
## JSON <small>v1.0.0 - v9.4.2</small>
1616

1717
Legacy (JSON) library save format versions were tied to the release version of the program itself. This number was stored in a `version` key inside the JSON file.
1818

@@ -28,21 +28,30 @@ Replaced by the new SQLite format introduced in TagStudio [v9.5.0 Pre-Release 1]
2828

2929
---
3030

31-
## SQLite
31+
## SQLite <small>v9.5.0+</small>
3232

3333
Starting with TagStudio [v9.5.0-pr1](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.0-pr1), the library save format has been moved to a [SQLite](https://sqlite.org) format. Legacy JSON libraries are migrated (with the user's consent) to the new format when opening in current versions of the program. The save format versioning is now separate from the program's versioning number.
3434

35+
### Versioning
36+
3537
Versions **1-100** stored the database version in a table called `preferences` in a row with the `key` column of `"DB_VERSION"` inside the corresponding `value` column.
3638

3739
Versions **>101** store the database version in a table called `versions` in a row with the `key` column of `'CURRENT'` inside the corresponding `value` column. The `versions` table also stores the initial database version in which the file was created with under the `'INITIAL'` key. Databases created before this key was introduced will always have `'INITIAL'` value of `100`.
3840

39-
```mermaid
40-
erDiagram
41-
versions {
42-
TEXT key PK "Values: ['INITIAL', 'CURRENT']"
43-
INTEGER value
44-
}
45-
```
41+
#### "versions" Table
42+
43+
| key (`VARCHAR`) | value (`INTEGER`) |
44+
| --------------- | --------------------------------------------- |
45+
| `'INITIAL'` | <Version DB was created with, minimum `100`\> |
46+
| `'CURRENT'` | <Current version of DB\> |
47+
48+
#### Major and Minor Versioning
49+
50+
Version **100** came along with a major/minor versioning system built into to the single version number. The version number divided by 100 denotes the major version, while remaining digits denote the minor version. TagStudio will allow reading from "future" databases so long as the major version does not increase past the last one it understands.
51+
52+
For example, a database with version 204 would still be readable in an older version of TagStudio that understands version 200. A database with version 300, on the other hand, would no longer be readable in that same older version and an error message would display.
53+
54+
---
4655

4756
### Versions 1 - 5
4857

@@ -95,13 +104,13 @@ Migration from the legacy JSON format is provided via a walkthrough when opening
95104

96105
---
97106

98-
### Versions 100 - 1xx
107+
### Versions 100 - 104
99108

100109
#### Version 100
101110

102-
| Used From | Format | Location |
103-
| --------- | ------ | ----------------------------------------------- |
104-
| 74383e3 | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
111+
| Used From | Format | Location |
112+
| ---------------------------------------- | ------ | ----------------------------------------------- |
113+
| 74383e3c3c12f72be1481ab0b86c7360b95c2d85 | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
105114

106115
- Introduces built-in minor versioning
107116
- The version number divided by 100 (and floored) constitutes the **major** version. Major version indicate breaking changes that prevent libraries from being opened in TagStudio versions older than the ones they were created in.
@@ -110,11 +119,11 @@ Migration from the legacy JSON format is provided via a walkthrough when opening
110119

111120
#### Version 101
112121

113-
| Used From | Format | Location |
114-
| ------------------------------------------------------------------------------- | ------ | ----------------------------------------------- |
115-
| 12e074b/[v9.5.4](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.4) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
122+
| Used From | Format | Location |
123+
| ---------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- |
124+
| 12e074b71d8860282b44e49e0e1a41b7a2e4bae8/[v9.5.4](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.4) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
116125

117-
- Deprecates the `preferences` table, set to be removed in a future TagStudio version.
126+
- Deprecates the `preferences` table, set to be removed in a [future](#version-104) TagStudio version.
118127
- Introduces the `versions` table
119128
- Has a string `key` column and an int `value` column
120129
- The `key` column stores one of two values: `'INITIAL'` and `'CURRENT'`
@@ -124,34 +133,36 @@ Migration from the legacy JSON format is provided via a walkthrough when opening
124133

125134
#### Version 102
126135

127-
| Used From | Format | Location |
128-
| --------- | ------ | ----------------------------------------------- |
129-
| 71d0425 | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
136+
| Used From | Format | Location |
137+
| ---------------------------------------- | ------ | ----------------------------------------------- |
138+
| 71d04254cf87f4200bb7ffc81656e50dfb122e4d | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
130139

131140
- Applies repairs to the `tag_parents` table created in [version 100](#version-100), removing rows that reference tags that have been deleted.
132141

133-
| Used From | Format | Location |
134-
| ------------------------------------------------------------------------------- | ------ | ----------------------------------------------- |
135-
| 88d0b47/[v9.5.7](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.7) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
142+
| Used From | Format | Location |
143+
| ---------------------------------------------------------------------------------------------------------------- | ------ | ----------------------------------------------- |
144+
| 88d0b47a86821ccfadba653f30a515abce5b24b0/[v9.5.7](https://github.com/TagStudioDev/TagStudio/releases/tag/v9.5.7) | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
136145

137146
- Adds the `is_hidden` column to the `tags` table (default `0`). Used for excluding entries tagged with hidden tags from library searches.
138147
- Sets the `is_hidden` field on the built-in Archived tag to `1`, to match the Archived tag now being hidden by default.
139148

140149
#### Version 104
141150

142-
| Used From | Format | Location |
143-
| --------- | ------ | ----------------------------------------------- |
144-
| ad2cbbc | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
151+
| Used From | Format | Location |
152+
| ---------------------------------------- | ------ | ----------------------------------------------- |
153+
| ad2cbbca483018d245b44348e2c4f5a0e0bb28f1 | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
145154

146155
- Removes the `preferences` table, after migrating the contained extension list to the .ts_ignore file, if necessary.
147156

157+
---
158+
148159
### Versions 200 - 2xx
149160

150161
#### Version 200
151162

152-
| Used From | Format | Location |
153-
| --------- | ------ | ----------------------------------------------- |
154-
| c15e2b5 | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
163+
| Used From | Format | Location |
164+
| ---------------------------------------- | ------ | ----------------------------------------------- |
165+
| c15e2b56eedd0a3c13391fa43571b8f8f7c7a91f | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
155166

156167
- Adds `text_field_templates` and `date_field_templates` tables.
157168
- Drops `boolean_fields` and `value_type` tables.
@@ -166,9 +177,9 @@ Migration from the legacy JSON format is provided via a walkthrough when opening
166177

167178
#### Version 201
168179

169-
| Used From | Format | Location |
170-
| --------- | ------ | ----------------------------------------------- |
171-
| TBD | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
180+
| Used From | Format | Location |
181+
| ---------------------------------------- | ------ | ----------------------------------------------- |
182+
| 38da7bb3a920a01d4d70fa065fd19c83ff6eecb1 | SQLite | `<Library Folder>`/.TagStudio/ts_library.sqlite |
172183

173184
- Drops `type_key` columns from `text_fields` and `datetime_fields` tables.
174185
- Enforces column positions for `text_fields` and `datetime_fields` tables.

‎docs/preview-support.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,8 @@ Archive thumbnails will display the first image from the archive within the Prev
124124
!!! failure "3D Model Support"
125125
TagStudio does not currently support previews for 3D model files *(outside of Blender project embedded thumbnails)*. This is on our [roadmap](roadmap.md#uiux) for a future release.
126126

127+
See the [GitHub discussion](https://github.com/TagStudioDev/TagStudio/discussions/1231) relating to status of this feature.
128+
127129
### :material-format-font: Fonts
128130

129131
Font thumbnails will use a "Aa" example preview of the font, with a full alphanumeric of the font available in the Preview Panel.
@@ -155,7 +157,7 @@ Text files render the first 256 bytes of text information to an image preview fo
155157

156158
<!-- prettier-ignore-start -->
157159
[^1]:
158-
The `.jpg_large` extension is unofficial and instead the byproduct of how [Google Chrome used to download images from Twitter](https://fileinfo.com/extension/jpg_large). Since this mangled extension is still in circulation, TagStudio supports it.
160+
The `.jpg_large` extension is unofficial and is instead the byproduct of how [Google Chrome used to download images from Twitter](https://fileinfo.com/extension/jpg_large). Since this mangled extension is still in circulation, TagStudio supports it.
159161

160162
[^2]:
161163
Apple Lossless traditionally uses `.m4a` and `.caf` containers, but may unofficially use the `.alac` extension. The `.m4a` container is also used for separate compressed audio codecs.

0 commit comments

Comments
 (0)