Skip to content

Commit 10b3ad8

Browse files
docs: clarify 2.0 as baseline for version admonitions
Updated versioning documentation to reflect that: - DataJoint 2.0 is the baseline for this documentation - Version admonitions (version-added, version-changed, version-deprecated) will only be used for features introduced in 2.1 and later - Features present in 2.0 are documented without version markers - Pre-2.0 migration info belongs in the Migration Guide, not admonitions Examples updated: - Changed "New in 2.0" → "New in 2.1" - Changed "Changed in 2.0" → "Changed in 2.1" - Changed "Deprecated in 2.0" → "Deprecated in 2.1" - Added note that 2.0 baseline features are not marked - Added note that pre-2.0 deprecations are in Migration Guide This keeps the documentation clean and focused on the current baseline while providing infrastructure for future version markers.
1 parent 1d22a67 commit 10b3ad8

File tree

1 file changed

+27
-20
lines changed

1 file changed

+27
-20
lines changed

src/about/versioning.md

Lines changed: 27 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ This page explains how version information is indicated throughout the DataJoint
66

77
**This documentation covers DataJoint 2.0 and later.** All code examples and tutorials use DataJoint 2.0+ syntax and APIs.
88

9+
**DataJoint 2.0 is the baseline.** Features and APIs introduced in 2.0 are documented without version markers, as they are the standard for this documentation.
10+
911
If you're using legacy DataJoint (version 0.14.x or earlier), please visit the [legacy documentation](https://datajoint.github.io/datajoint-python) or follow the [Migration Guide](../how-to/migrate-to-v20.md) to upgrade.
1012

1113
## Version Indicators
@@ -18,53 +20,58 @@ If you're using legacy DataJoint (version 0.14.x or earlier), please visit the [
1820

1921
### Feature-Level Indicators
2022

21-
For specific features, you'll see version admonitions:
23+
Version admonitions are used for features introduced **after 2.0** (i.e., version 2.1 and later):
2224

2325
#### New Features
2426

25-
!!! version-added "New in 2.0"
27+
!!! version-added "New in 2.1"
28+
29+
This indicates a feature that was introduced after the 2.0 baseline.
2630

27-
This indicates a feature that was introduced in DataJoint 2.0.
31+
**Example usage:**
2832

29-
**Example from documentation:**
33+
!!! version-added "New in 2.1"
3034

31-
!!! version-added "New in 2.0"
35+
The `dj.Top` operator with ordering support was introduced in DataJoint 2.1.
3236

33-
Semantic matching validates joins based on lineage tracking. This feature was introduced in DataJoint 2.0.
37+
**Note:** Features present in DataJoint 2.0 (the baseline) are not marked with version indicators.
3438

3539
#### Changed Behavior
3640

37-
!!! version-changed "Changed in 2.0"
41+
!!! version-changed "Changed in 2.1"
3842

39-
This indicates behavior that changed from previous versions.
43+
This indicates behavior that changed in a post-2.0 release.
4044

41-
**Example from documentation:**
45+
**Example usage:**
4246

43-
!!! version-changed "Changed in 2.0"
47+
!!! version-changed "Changed in 2.1"
4448

45-
The fetch API was redesigned in 2.0. Use `to_dicts()` or `to_arrays()` instead of `fetch()`.
49+
The `populate()` method now supports priority-based scheduling by default.
4650

47-
**Legacy (pre-2.0):** `data = table.fetch()`
48-
**Current (2.0+):** `data = table.to_dicts()`
51+
Use `priority=50` to control execution order when using `reserve_jobs=True`.
4952

5053
#### Deprecated Features
5154

52-
!!! version-deprecated "Deprecated in 2.0, removed in 3.0"
55+
!!! version-deprecated "Deprecated in 2.1, removed in 3.0"
5356

5457
This indicates features that are deprecated and will be removed in future versions.
5558

56-
**Example from documentation:**
59+
**Example usage:**
5760

58-
!!! version-deprecated "Deprecated in 2.0, removed in 3.0"
61+
!!! version-deprecated "Deprecated in 2.1, removed in 3.0"
5962

60-
The `external` storage type is deprecated. Use unified stores with `<blob@store>` syntax instead.
63+
The `allow_direct_insert` parameter is deprecated. Use `dj.config['safemode']` instead.
64+
65+
**Note:** Features deprecated at the 2.0 baseline (coming from pre-2.0) are documented in the [Migration Guide](../how-to/migrate-to-v20.md) rather than with admonitions, since this documentation assumes 2.0 as the baseline.
6166

6267
### Inline Version Badges
6368

64-
In API reference documentation, you may see inline version badges:
69+
For features introduced **after 2.0**, inline version badges may appear in API reference:
70+
71+
- `dj.Top()` <span class="version-badge">v2.1+</span> - Top N restriction with ordering
72+
- `some_method()` <span class="version-badge deprecated">deprecated</span> - Legacy method
6573

66-
- `to_dicts()` <span class="version-badge">v2.0+</span> - Retrieve as list of dicts
67-
- `fetch()` <span class="version-badge deprecated">deprecated</span> - Legacy fetch API
74+
**Note:** Methods and features present in DataJoint 2.0 (the baseline) do not have version badges.
6875

6976
## Checking Your Version
7077

0 commit comments

Comments
 (0)