Landing page improvements and migration guide enhancements#101
Merged
dimitri-yatsenko merged 17 commits intomainfrom Jan 14, 2026
Merged
Landing page improvements and migration guide enhancements#101dimitri-yatsenko merged 17 commits intomainfrom
dimitri-yatsenko merged 17 commits intomainfrom
Conversation
- Fix broken bullet lists in Step 7 by adding blank lines before bullets - Add semantic matching reference link to Query API Changes table - Wrap AI agent prompt lines to 82 characters for readability - Simplify dj.U() * table guidance: replace with just table (was hack) - Update all references to dj.U() * table pattern throughout document - Verify fetch(as_dict=True) → to_dicts() conversion is correct
- Add AI agent prompt for configuring and testing stores - Add test section with example code for all in-store codecs - Explain hash-addressed storage structure and properties - Link to Object Store Configuration spec (hash-addressed section) - Update Phase I checklist with store testing requirements - Fix checklist to exclude <npy@> (new in 2.0, not migration) Testing covers: - <blob@> hash-addressed blob storage - <attach@> hash-addressed attachments - <filepath@> filepath references - File organization verification - Understanding hash-based path generation Learn more: ../reference/specs/object-store-configuration.md#hash-addressed-storage
- Add new Step 3 after branching to update dj.schema() calls with _v2 suffix - Critical for parallel testing without affecting production schemas - Renumber subsequent steps: old 3-8 become new 4-9 - Update all cross-references to reflect new step numbers - Add AI agent prompt for schema declaration updates - Update table definitions prompt context (schemas already updated) Step sequence now: 1. Protect production 2. Create migration branch 3. Update schema declarations (_v2 suffix) ← NEW 4. Configure DataJoint 2.0 5. Configure test stores 6. Convert table definitions 7. Convert query/insert code 8. Update populate methods 9. Verify Phase I complete This enables side-by-side testing and validation in Phase II.
- Update test date examples: 2025-01-14 → 2026-01-14 - Update backup timestamp format: 20250114 → 20260114
- Replace Analysis.populate(order='priority DESC') with populate(priority=50) - The populate() method has a priority parameter (filter by priority level) - There is no 'order' parameter - jobs are automatically ordered by (priority, scheduled_time) - See ../reference/specs/autopopulate.md for correct API
- Replace detailed code examples with concise feature descriptions - Add structured learning path with tutorial links - Emphasize incremental adoption (no need to adopt all features) - Clarify priority parameter requires reserve_jobs=True Phase IV now focuses on: 1. Overview of new features (schema-addressed storage, semantic matching, Jobs 2.0, custom codecs) 2. Learning path: Start with tutorials, then reference docs 3. Incremental adoption strategy Links to: - Object Storage Tutorial (06-object-storage.ipynb) - Distributed Computing Tutorial (distributed.ipynb) - Custom Codecs Tutorial (custom-codecs.ipynb) - Reference specs for each feature Reduces duplication - full examples live in tutorials, migration guide focuses on migration process and points to learning resources.
Added blank lines after 16 bold section headers that were directly followed by bullet lists: - Why do this first: - Next steps: - Properties: - Fetch API: - Update Method: - Join Operators: - Universal Set: - Visualization: - You now have: (2 instances) - Both APIs work: - Pre-cutover checklist: - Adopt features incrementally: - Core Documentation: - Tutorials: - Specifications: All bullet lists now render correctly per markdown specification.
Replace specific pipeline examples with general guidance: **Before:** - Detailed examples with Mouse, Session, Neuron tables - Specific insert/populate code snippets - Prescriptive query testing examples - Long validation scripts with specific table names **After:** - Step 1: Run Your Regular Workflow - Use existing data entry processes - Use existing populate processes - Test with representative subset - Follow normal workflow, not artificial examples - Step 2: Compare with Legacy (equivalence testing) - Step 3: Run Existing Tests (if available) - Step 4: Document Test Results (general guidance) **Rationale:** - Every pipeline is different - specific examples aren't helpful - Users know their own workflows better than generic examples - Focus on the process, not prescriptive code - Removed ~150 lines of irrelevant examples Phase II now tells users WHAT to do (run their workflow, compare results, document) rather than HOW their specific tables should work.
Add prominent recommendation to create tests before starting migration, enabling automated agent-driven migration. **Added early callout (before 'What's New'):** - Highlights 50-80% effort reduction with tests - Links to detailed recommendation section **Added detailed section (before Phase I):** - Why tests enable automation (Phases I-II mostly automated) - What tests to create (unit + integration against QA database) - Example test structure (pytest with fixtures) - How agents use tests (iterative fix-test-verify loop) - Investment vs. return (~1-3 days saves weeks of manual work) - When to skip (simple pipelines, time pressure) **Key benefits:** With tests: - Phase I: Agent migrates code → runs tests → fixes failures → done - Phase II: Agent populates data → runs tests → compares → reports - Phase III: Immediate verification after data migration Without tests: - Manual verification at every step - Higher risk of missed issues - More time-intensive validation Tests pay for themselves during migration and provide ongoing value for future development. Highly recommended for complex pipelines.
- Changed Platform link from about/platform.md to https://www.datajoint.com/sign-up - Platform documentation page no longer accessible via navigation - File src/about/platform.md still exists but is not linked
- Add pipeline illustration image at top (pipeline-illustration.png) - Add pre-2.0 documentation link to callout (docs.datajoint.com/python-0.x/) - Add DataJoint Elements card to main grid for prominent visibility - Follows structure of legacy documentation landing page
- Quick Start now at top of tutorials/index.md (learning content belongs in tutorials) - Landing page simplified to focus on navigation - Added brief call-to-action linking to Quick Start tutorial - Follows Diataxis framework (landing for navigation, tutorials for learning)
- Changed from docs.datajoint.com/python-0.x/ to datajoint.github.io/datajoint-python - Points to current gh-pages deployment (version 0.14) - Legacy docs are effectively frozen (manual workflow trigger only)
- Fixed migration guide link: how-to/migrate-from-0x.md → how-to/migrate-to-v20.md - Added DataJoint Platform card to main grid (matching legacy docs structure) - Platform card links to datajoint.com and works.datajoint.com sign-in
- Removed how-to/migrate-from-0x.md (replaced by migrate-to-v20.md) - All references now point to how-to/migrate-to-v20.md
- Changed from local images/pipeline-illustration.png to GitHub raw URL - Uses https://raw.githubusercontent.com/datajoint/datajoint-python/master/images/pipeline.png - Matches legacy documentation image source
- Copied pipeline.png from datajoint-python to src/images/ - Moved image to appear after first paragraph (DataJoint definition) - Changed from external URL to local path (images/pipeline.png) - Better visual flow with definition → illustration → details
kavenk
approved these changes
Jan 14, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR improves the landing page structure and enhances the migration guide with testing recommendations and clearer workflows.
Landing Page Changes
Migration Guide Enhancements
_v2suffix for parallel testingorderparameter, usepriorityinstead)Navigation Changes
Files Changed
src/index.md- Landing page restructuresrc/tutorials/index.md- Added Quick Start sectionsrc/how-to/migrate-to-v20.md- Major enhancementsmkdocs.yaml- Platform link redirectsrc/images/pipeline.png- Added pipeline illustrationsrc/how-to/migrate-from-0x.md- Removed (obsolete)Testing
Landing page structure follows legacy documentation layout while serving 2.0 content. Migration guide tested for link validity and formatting.