Upgrading Telar To 0.6.2-beta: A Step-by-Step Guide

Dec 4, 2025 by Alex Johnson 52 views

Are you looking to upgrade your Telar installation to the latest version, 0.6.2-beta? This comprehensive guide will walk you through the entire process, ensuring a smooth and successful update. We'll cover everything from the automated steps to the manual configurations, and provide helpful tips along the way. Let's dive in and get your Telar site running on the newest features and improvements!

Upgrade Ready: v0.6.1-beta → v0.6.2-beta

The good news is that the automated upgrade process is complete! The upgrade from version 0.6.1-beta to 0.6.2-beta has been successfully executed. You'll find the changes in the upgrade-telar-0.6.2-beta branch. This upgrade included 16 automated changes and 2 manual steps. This means the bulk of the work is already done, and we just need to review and finalize the upgrade.

Next Step: Review and Merge

Now, let's move on to the crucial step of reviewing the changes and merging them into your main branch. This ensures that the updated code integrates seamlessly with your existing Telar site.

Reviewing Changes and Creating a Pull Request

To get started, click here to review changes and create a pull request. This link will take you directly to a comparison view on GitHub, where you can see all the modifications made during the automated upgrade. Next, click the green "Create pull request" button. Take your time to carefully review each change, ensuring that everything looks as expected. Once you're satisfied, merge the pull request to complete this stage of the upgrade.

Command Line Instructions (Optional)

For those who prefer working from the command line, here's how you can merge the upgrade branch:

git fetch origin
git checkout main
git merge origin/upgrade-telar-0.6.2-beta
git push origin main

While this method works, we highly recommend using the pull request method described above. The pull request interface provides a much better environment for reviewing changes, making the process smoother and less prone to errors.

After Merging: Manual Steps and Verification

Once you've merged the upgrade, there are a few manual steps to complete and some verification to perform. This ensures that your Telar site is running perfectly on the new version.

Manual Steps to Complete

There are two sets of manual steps, depending on how you deploy your Telar site:

If you use GitHub Pages:

Great news! No further actions are needed. Your site will automatically take advantage of the improved viewer preloading feature when it rebuilds. GitHub Pages handles the deployment process seamlessly. This is the simplest option, as GitHub Pages automatically rebuilds your site whenever changes are pushed to the main branch. The new viewer preloading will enhance the user experience by loading content more efficiently.
If you work with your site locally:

A new all-in-one build script is now available, making local development much easier. To use it, simply run the following command:
```
python3 scripts/build_local_site.py
```
This script automates all the necessary build steps, including CSV conversion, collections generation, IIIF processing, and Jekyll build. For faster rebuilds when images haven't changed, you can use the --skip-iiif flag:
```
python3 scripts/build_local_site.py --skip-iiif
```
This new script significantly streamlines the local development workflow, making it easier to test and deploy changes.

Verifying Your Upgraded Site

After completing the upgrade and allowing your site to rebuild, it's crucial to verify that everything is working correctly. Follow these steps to ensure a smooth transition:

Visit your live site and navigate through a few pages:

This initial check helps you get a feel for the overall performance and layout of your site. Click through different sections, such as the homepage, individual stories, and collection pages. This will give you a quick overview of whether the upgrade has introduced any obvious issues.
Check for any warning messages or alerts about configuration issues:

Pay close attention to any messages that appear on your site, especially those related to configuration. These warnings can indicate potential problems that need to be addressed. Look for messages in the console, the footer, or any other designated area for alerts.
If you see any warnings, follow the links or documentation provided to resolve them:

Most warnings will come with links to documentation or specific instructions on how to fix the underlying issue. Follow these guides carefully to ensure that your site is properly configured. Resolving warnings promptly is crucial for maintaining the stability and performance of your site.
Test key features like story navigation, image viewing, and glossary terms:

This is where you delve into the core functionalities of your Telar site. Ensure that story navigation is working smoothly, images are loading correctly, and glossary terms are properly linked and displayed. This comprehensive testing will help you identify any potential issues that might have slipped through the initial checks.
Close this issue once everything is working - this marks the upgrade as complete:

Once you've verified that all features are functioning as expected, you can close the upgrade issue. This signifies that the upgrade process is complete and your Telar site is successfully running on version 0.6.2-beta.

What Changed in Version 0.6.2-beta?

Now, let's take a look at the key changes introduced in the 0.6.2-beta release. Understanding these changes will help you appreciate the improvements and new features.

Upgrade Summary

From: 0.6.1-beta
To: 0.6.2-beta
Date: 2025-12-04
Automated changes: 16
Manual steps: 2

This summary provides a quick overview of the upgrade process, highlighting the number of automated and manual steps involved.

Automated Changes Applied

The automated changes cover a wide range of areas, from configuration to scripts. Here’s a breakdown by category:

Configuration (3 files)

Renamed config section: testing-features → development-features

This change clarifies the purpose of the configuration section, making it more intuitive for developers.
Updated _layouts/story.html: Story layout (viewer preloading config)

This update introduces the improved viewer preloading feature, which enhances the user experience by loading content more efficiently. The configuration settings in the story layout have been adjusted to support this new functionality.
Updated _config.yml: Version 0.6.2-beta (2025-12-04)

This update simply reflects the new version number and release date in the main configuration file.

Layouts (2 files)

Updated _layouts/index.html: Index layout (hover prefetch, hide flags)

The index layout has been updated with hover prefetch functionality, which anticipates user actions and loads content in advance, further improving performance. Additionally, hide flags have been added to control the visibility of certain elements on the index page.
Updated _layouts/objects-index.html: Objects index (hide_collections flag)

This update introduces the hide_collections flag, allowing you to control whether collections are displayed on the objects index page. This provides greater flexibility in organizing and presenting your content.

Includes (3 files)

Updated _includes/viewer.html: Viewer include (removed inline transition styles)

Inline transition styles have been removed from the viewer include, promoting cleaner code and better maintainability. This change also allows for more consistent styling across the site.
Updated _includes/header.html: Header (hide_collections nav flag)

The header include has been updated with the hide_collections navigation flag, allowing you to control whether collections are displayed in the main navigation menu. This provides greater control over the site's navigation structure.
Updated _includes/panels.html: Panels (h5→h1 semantic fix)

This update addresses a semantic issue by changing the heading level from h5 to h1 in the panels include. This improves the site's accessibility and SEO by ensuring proper heading structure.

Styles (1 file)

Updated assets/css/telar.scss: Stylesheet (image overflow, h1 spacing, fade transitions)

The main stylesheet has been updated with several improvements, including fixes for image overflow issues, adjustments to h1 spacing, and enhancements to fade transitions. These changes contribute to a more polished and visually appealing user experience.

Scripts (5 files)

Updated assets/js/story.js: Story JS (viewer preloading overhaul)

This is a significant update that overhauls the viewer preloading functionality, making it more efficient and reliable. This improvement ensures that content loads quickly and smoothly, enhancing the overall user experience.
Updated assets/js/telar.js: Telar JS (glossary-to-glossary linking)

This update introduces glossary-to-glossary linking, allowing users to easily navigate between related terms within the glossary. This feature enhances the site's usability and helps users explore the content more effectively.
Updated scripts/csv_to_json.py: CSV converter (case-insensitive matching)

The CSV converter script has been updated to support case-insensitive matching, making it more flexible and robust. This improvement simplifies the process of importing data from CSV files.
Updated scripts/generate_collections.py: Collections generator (glossary links, hide flags)

The collections generator script has been updated to include glossary links and hide flags, providing greater control over the generation of collection pages. These enhancements make it easier to create and manage collections within your Telar site.
Updated scripts/build_local_site.py: NEW: All-in-one local build script

This new script is a major addition that streamlines the local build process. It automates all the necessary steps, making it easier to develop and test your Telar site locally.

Documentation (1 file)

Updated README.md: README (version update)

The README file has been updated to reflect the new version number, ensuring that users have the most up-to-date information about the project.

Other (1 file)

Updated CHANGELOG.md: CHANGELOG (v0.6.2 release notes)

The CHANGELOG file has been updated with detailed release notes for version 0.6.2, providing a comprehensive overview of the changes and improvements included in this release.

Manual Steps Required

As mentioned earlier, there are two manual steps to complete after merging the upgrade:

If you use GitHub Pages:

No further actions are needed. Your site will automatically use the improved viewer preloading when it rebuilds.
If you work with your site locally:

A new all-in-one build script is now available:
```
python3 scripts/build_local_site.py
```
This runs all build steps (CSV conversion, collections, IIIF, Jekyll) with a single command. Use --skip-iiif for faster rebuilds when images haven't changed.

Resources

For further information and assistance, please refer to the following resources:

These resources provide detailed documentation, release notes, and a platform for reporting any issues you may encounter.

Conclusion

Upgrading Telar to version 0.6.2-beta brings a host of improvements and new features that enhance both the user experience and the development workflow. By following this step-by-step guide, you can ensure a smooth and successful upgrade. Remember to review the changes carefully, complete the manual steps, and verify that everything is working correctly. Happy upgrading!

For more information about version control and Git, check out Git Documentation. This comprehensive resource will help you understand and utilize Git effectively in your projects.

_{This upgrade was performed automatically by the Telar upgrade workflow.}