Telar Upgrade Guide: V0.6.1-beta To V0.6.2-beta

by Alex Johnson 48 views

Are you looking to upgrade your Telar site to the latest version, v0.6.2-beta? This guide provides a detailed walkthrough of the upgrade process, ensuring a smooth transition and access to the latest features and improvements. This comprehensive guide will walk you through each step, from automated changes to manual verifications, ensuring your site benefits from the latest enhancements.

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

The upgrade to Telar v0.6.2-beta is now complete, bringing with it a host of improvements and new features. The automated upgrade process has been successfully executed, and your site is almost ready to go. This section provides an overview of the upgrade status and the steps required to finalize the process.

Status: ✅ Automated upgrade complete

The automated upgrade process has been successfully completed, laying the groundwork for the new version. This means that the system has automatically applied several changes to your Telar site, streamlining the transition to v0.6.2-beta. These automated changes include configuration updates, layout enhancements, and script modifications, all designed to improve the performance and functionality of your site.

Branch: upgrade-telar-0.6.2-beta

The changes for this upgrade have been applied to a dedicated branch, upgrade-telar-0.6.2-beta. This ensures that the upgrade process doesn't directly affect your main site until you've had a chance to review and merge the changes. Working with a separate branch allows for a controlled and safe upgrade, minimizing the risk of disruptions to your live site.

Changes: 20 automated, 2 manual

The upgrade includes a total of 22 changes, with 20 of them being automated. These automated changes cover a wide range of updates, from configuration tweaks to script enhancements. The remaining 2 steps require manual intervention to ensure a seamless transition. These manual steps are crucial for tailoring the upgrade to your specific setup and verifying that everything functions as expected.

Next Step: Review and Merge

Now that the automated upgrade is complete, the next crucial step is to review the changes and merge them into your main branch. This process ensures that the new version of Telar is fully integrated into your site, allowing you to take advantage of all the latest features and improvements. Thoroughly reviewing the changes before merging is essential to identify any potential issues and ensure a smooth transition.

Click here to review changes and create pull request

The first step in this process is to review the changes made during the automated upgrade. By clicking the provided link, you'll be directed to a detailed comparison of the changes between your main branch and the upgrade branch. This comparison allows you to see exactly what has been modified, added, or removed during the upgrade process. Take your time to carefully examine each change, ensuring you understand its purpose and impact on your site. This step is vital for identifying any potential conflicts or issues before they affect your live site.

Then, click the green "Create pull request" button, review the changes, and merge to complete the upgrade.

Once you've reviewed the changes, the next step is to create a pull request. This initiates the process of merging the changes from the upgrade branch into your main branch. Click the green "Create pull request" button to begin this process. Before finalizing the merge, you'll have another opportunity to review the changes in the pull request interface. This allows for a final check to ensure everything is in order. After confirming that all changes are correct and compatible with your site, you can proceed to merge the pull request. Merging the changes integrates the new version of Telar into your main branch, making the updated site live.

For users who prefer the command line (click to expand)

If you prefer working from your terminal:

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

This will merge the upgrade branch into your main branch. We recommend using the pull request method above instead, as it provides a better review interface.

For those who prefer a more hands-on approach, the command line offers an alternative method for merging the changes. The provided commands allow you to fetch the latest updates, switch to your main branch, merge the upgrade branch, and push the changes to your remote repository. While this method is efficient, it's recommended to use the pull request method for a better review interface. The pull request interface provides a clear and organized way to examine the changes, ensuring that all modifications are thoroughly vetted before being merged into the main branch.

After Merging

After successfully merging the upgrade, there are a few crucial steps to take to ensure your site is running smoothly and optimally. This section outlines the manual steps required post-merge and provides guidance on verifying the upgrade's success. Completing these steps is essential for a seamless transition to the new version of Telar.

Once you've merged the upgrade, please complete the following:

Manual Steps

Completing the manual steps ensures that the upgrade is fully integrated and your site functions as expected. These steps are tailored to specific scenarios and require your attention to ensure a smooth transition.

  1. If you use GitHub Pages:

No further actions needed. Your site will automatically use the improved viewer preloading when it rebuilds.

If your site is hosted on GitHub Pages, the upgrade process is largely automatic. GitHub Pages will handle the rebuild of your site, incorporating the new version of Telar and its improved viewer preloading feature. This means you don't need to perform any additional steps to benefit from the upgrade. The automated rebuild process ensures that your site is always running the latest version, with all the enhancements and bug fixes included in the upgrade.

  1. 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.

For those who work with their Telar site locally, a new all-in-one build script is available to simplify the build process. This script, python3 scripts/build_local_site.py, automates all the necessary steps for building your site, including CSV conversion, collections generation, IIIF processing, and Jekyll build. By running this single command, you can ensure that your local site is up-to-date with the latest changes. The --skip-iiif option allows for faster rebuilds when image assets haven't been modified, further streamlining the development process.

Verify Your Site

Verification is a critical step in the upgrade process. It ensures that the new version of Telar is functioning correctly and that all features are working as expected. This process involves checking various aspects of your site, from navigation to content display, to identify and address any potential issues.

After the upgrade completes and your site rebuilds:

  1. Visit your live site and navigate through a few pages

Start by visiting your live site and navigating through different pages. This initial step allows you to get a general overview of the site's appearance and functionality. Check that the layout is rendering correctly, and that the navigation menus are working as expected. By exploring various sections of your site, you can quickly identify any major issues that may require attention.

  1. Check for any warning messages or alerts about configuration issues

Pay close attention to any warning messages or alerts that may appear on your site. These messages often indicate configuration issues or potential problems that need to be addressed. Configuration issues can arise from changes in the upgrade process, so it's important to resolve them promptly to ensure your site functions correctly. The presence of warning messages is a key indicator that further investigation is needed.

  1. If you see any warnings, follow the links or documentation provided to resolve them

If you encounter any warning messages, follow the links or documentation provided to troubleshoot and resolve the issues. These resources often offer specific guidance on how to address common problems that may arise during the upgrade process. By following the recommended steps, you can quickly identify the root cause of the issue and implement the necessary fixes. Addressing warnings promptly ensures that your site remains stable and performs optimally.

  1. Test key features like story navigation, image viewing, and glossary terms

Test key features of your site, such as story navigation, image viewing, and glossary terms, to ensure they are functioning correctly. This comprehensive testing helps to verify that all critical components of your site are working as expected after the upgrade. By thoroughly testing these features, you can identify any potential issues that may not be immediately apparent.

  1. Close this issue once everything is working - this marks the upgrade as complete

Once you've verified that everything is working correctly, close the issue to mark the upgrade as complete. This final step signals that the upgrade process has been successfully executed and that your site is now running the latest version of Telar. Closing the issue helps to keep track of completed upgrades and ensures that all necessary steps have been taken.

What Changed

The upgrade to Telar v0.6.2-beta introduces several significant changes and improvements. This section provides a detailed overview of the automated changes and manual steps involved in the upgrade. Understanding these changes is crucial for ensuring a smooth transition and maximizing the benefits of the new version.

View automated changes by category (click to expand)

Upgrade Summary

This summary provides a high-level overview of the upgrade, including the versions involved, the date of the upgrade, and the number of automated changes and manual steps.

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

Automated Changes Applied

The automated changes cover a wide range of updates, from configuration tweaks to script enhancements. This section provides a detailed list of the changes applied during the automated upgrade process.

Configuration (3 files)

Configuration changes involve updates to settings and parameters that control how your Telar site functions. These changes ensure that the site is properly configured to run the new version of Telar.

  • [x] Renamed config section: testing-features → development-features

    The configuration section testing-features has been renamed to development-features. This change aligns the configuration naming with standard development practices, making it clearer that these features are intended for development environments. The new name helps to avoid confusion and ensures that testing-related configurations are properly managed.

  • [x] Updated _layouts/story.html - Story layout (viewer preloading config)

    The _layouts/story.html file, which defines the layout for story pages, has been updated to include viewer preloading configurations. Viewer preloading is a performance enhancement that loads viewer resources in advance, resulting in faster loading times and a smoother user experience. This update ensures that story pages load quickly and efficiently.

  • [x] Updated _config.yml: version 0.6.2-beta (2025-12-04)

    The main configuration file, _config.yml, has been updated to reflect the new version number (0.6.2-beta) and the upgrade date (2025-12-04). This update ensures that the site's configuration accurately reflects the current version and provides a record of when the upgrade was performed. Keeping the configuration file up-to-date is essential for maintaining the site's integrity and tracking changes.

Layouts (2 files)

Layout updates involve changes to the structure and design of your site's pages. These updates ensure that the site's layout is consistent with the new version of Telar and that all elements are displayed correctly.

  • [x] Updated _layouts/index.html - Index layout (hover prefetch, hide flags)

    The _layouts/index.html file, which defines the layout for the homepage, has been updated to include hover prefetch and hide flags. Hover prefetch is a performance optimization technique that preloads linked resources when a user hovers over a link, resulting in faster page transitions. The hide flags allow for greater control over which elements are displayed on the homepage. This update enhances both the performance and customization options for the homepage.

  • [x] Updated _layouts/objects-index.html - Objects index (hide_collections flag)

    The _layouts/objects-index.html file, which defines the layout for the objects index page, has been updated to include the hide_collections flag. This flag allows you to control whether collections are displayed on the objects index page, providing greater flexibility in how content is organized and presented. The hide_collections flag is useful for simplifying the user interface and focusing attention on specific types of content.

Includes (3 files)

Includes are reusable code snippets that are included in various parts of your site. Updates to includes ensure that these snippets are consistent with the new version of Telar and that they function correctly across the site.

  • [x] Updated _includes/viewer.html - Viewer include (removed inline transition styles)

    The _includes/viewer.html file, which defines the viewer component, has been updated to remove inline transition styles. Inline styles can make it harder to manage and override styles, so removing them promotes a cleaner and more maintainable codebase. This update ensures that the viewer component's styles are defined in a central stylesheet, making it easier to customize and update the viewer's appearance.

  • [x] Updated _includes/header.html - Header (hide_collections nav flag)

    The _includes/header.html file, which defines the site header, has been updated to include the hide_collections navigation flag. This flag allows you to control whether collections are displayed in the navigation menu, providing greater flexibility in how the site's navigation is structured. The hide_collections flag can be used to simplify the navigation menu and focus attention on key content areas.

  • [x] Updated _includes/panels.html - Panels (h5→h1 semantic fix)

    The _includes/panels.html file, which defines the panels component, has been updated to correct a semantic issue by changing h5 tags to h1 tags. Using the correct heading tags improves the site's structure and accessibility, making it easier for search engines and assistive technologies to understand the content. This update enhances the site's SEO and accessibility.

Styles (1 file)

Style updates involve changes to the site's stylesheets, which control the visual appearance of the site. These updates ensure that the site's styles are consistent with the new version of Telar and that the site looks its best.

  • [x] Updated assets/css/telar.scss - Stylesheet (image overflow, h1 spacing, fade transitions)

    The main stylesheet, assets/css/telar.scss, has been updated to address image overflow issues, improve h1 spacing, and enhance fade transitions. Fixing image overflow ensures that images are displayed correctly and don't break the layout. Improving h1 spacing enhances the visual hierarchy and readability of the content. Enhancing fade transitions adds visual polish to the site, making it more engaging for users. These updates collectively improve the site's aesthetics and user experience.

Scripts (5 files)

Script updates involve changes to the site's JavaScript files, which control the interactive behavior of the site. These updates ensure that the site's scripts are compatible with the new version of Telar and that all interactive features function correctly.

  • [x] Updated assets/js/story.js - Story JS (viewer preloading overhaul)

    The assets/js/story.js file, which controls the behavior of story pages, has been updated to overhaul the viewer preloading functionality. This update significantly improves the performance of viewer preloading, resulting in faster loading times and a smoother user experience. The viewer preloading overhaul ensures that story pages load quickly and efficiently.

  • [x] Updated assets/js/telar.js - Telar JS (glossary-to-glossary linking)

    The main JavaScript file, assets/js/telar.js, has been updated to add glossary-to-glossary linking. This feature allows you to create links between glossary terms, making it easier for users to navigate and understand the site's content. Glossary-to-glossary linking enhances the site's usability and information architecture.

  • [x] Updated scripts/csv_to_json.py - CSV converter (case-insensitive matching)

    The CSV converter script, scripts/csv_to_json.py, has been updated to support case-insensitive matching. This enhancement makes the CSV conversion process more flexible and robust, allowing you to work with CSV files that may have inconsistent casing. Case-insensitive matching ensures that data is processed correctly regardless of the casing used in the CSV file.

  • [x] Updated scripts/generate_collections.py - Collections generator (glossary links, hide flags)

    The collections generator script, scripts/generate_collections.py, has been updated to include glossary links and hide flags. This update makes it easier to generate collections with glossary links and to control the visibility of collections on the site. The new features enhance the flexibility and customization options for collections.

  • [x] Updated scripts/build_local_site.py - NEW: All-in-one local build script

    A new all-in-one local build script, scripts/build_local_site.py, has been added. This script automates all the necessary steps for building your site locally, including CSV conversion, collections generation, IIIF processing, and Jekyll build. The all-in-one script simplifies the local development process and ensures that all build steps are executed consistently.

Documentation (1 file)

Documentation updates ensure that the site's documentation is up-to-date with the new version of Telar. These updates provide users with the information they need to use the new features and enhancements.

  • [x] Updated README.md - README (version update)

    The README.md file, which provides an overview of the site, has been updated to reflect the new version number. This update ensures that users are aware of the current version of Telar being used on the site. Keeping the README file up-to-date is essential for providing accurate information to users and contributors.

Other (5 files)

This category includes changes that don't fit into the other categories, such as updates to the changelog and removal of deprecated files.

  • [x] Updated CHANGELOG.md - CHANGELOG (v0.6.2 release notes)

    The CHANGELOG.md file, which provides a record of changes made to the site, has been updated to include the release notes for v0.6.2. This update ensures that users are aware of the changes and improvements included in the new version. The changelog provides a valuable resource for understanding the evolution of the site.

  • [x] Removed deprecated: components/texts/glossary/colonial-period.md

  • [x] Kept (user modified): components/texts/glossary/reduccion.md

  • [x] Removed deprecated: components/texts/glossary/resguardo.md

  • [x] Removed deprecated: components/texts/glossary/viceroyalty.md

    Deprecated files, such as glossary terms, have been removed to clean up the codebase and improve maintainability. Deprecated files are those that are no longer used or supported, so removing them helps to reduce clutter and potential confusion. However, if a file has been user-modified, it is kept to preserve any custom changes.

Manual Steps Required

The manual steps required after merging the upgrade are outlined here. These steps ensure that your site is fully functional and optimized for the new version of Telar.

Please complete these after merging:

  1. If you use GitHub Pages:

    No further actions needed. Your site will automatically use the improved viewer preloading when it rebuilds.

  2. 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

This section provides links to valuable resources that can help you with the upgrade process and with using Telar in general.

Conclusion

Upgrading your Telar site to v0.6.2-beta brings a range of improvements and new features designed to enhance both the performance and functionality of your site. This comprehensive guide has walked you through each step of the upgrade process, from the initial automated changes to the final verification steps. By following these guidelines, you can ensure a smooth transition and take full advantage of the latest enhancements. Remember to review all changes carefully, complete the necessary manual steps, and thoroughly verify your site to ensure everything is working as expected. With the upgrade complete, your Telar site will be better equipped to deliver a seamless and engaging experience to your users.

For more information about Telar and its features, be sure to visit the official Telar Documentation. This resource provides comprehensive guides, tutorials, and API references to help you get the most out of your Telar site.

This upgrade was performed automatically by the Telar upgrade workflow.