Ghost Release: 4.0.0-alpha.1

TL;DR

Ghost 4.0.0-alpha.1 introduces significant architectural changes to prepare for future decoupling of Ghost components. This alpha release includes a new linear boot process, database schema changes, and improved social media metadata handling. It also removes legacy apps-related tables and code, changes post/page slug constraints, and adds member subscription event tracking. This is an early prerelease intended for testing migrations and tooling.

Key changes include database schema improvements, enhanced social media metadata handling, and foundational work for the API v3 as the new default. While this is an alpha release with ongoing development, it represents important groundwork for Ghost's future architecture.

Highlight of the Release

• New linear boot process for simpler, clearer Ghost startup
• Changed unique constraint in posts table from slug to slug+type, allowing posts and pages to have the same slug
• Improved Twitter/OG structured data rules with better fallback logic
• Added member subscription event tracking
• Migrated default API version from v2 to v3

Migration Guide

Content Helper Template Change

If you're a theme developer using custom templates named content.hbs with the {{content}} helper inside them, be aware that the helper now uses content-cta.hbs for its CTA template to avoid infinite loops. Update your theme accordingly if you've customized this aspect.

API Version Change

The default API version has been migrated from v2 to v3. If you have integrations or custom code that relies on the default API version, ensure they're compatible with v3.

Database Schema Changes

If you have custom code that interacts directly with Ghost's database schema:

• The apps-related tables (apps_*) have been dropped
• The posts table now has a unique constraint on slug+type instead of just slug
• A new members_subscribe_events table has been added

Boot Process Changes

For developers working with Ghost's boot process, note that there's a new ghost.js file that allows switching between boot modes with node index or node index old. The old boot process will be removed in future releases.

Upgrade Recommendations

As this is an alpha release (4.0.0-alpha.1), it is not recommended for production environments. This release is specifically intended for testing migrations and tooling.

If you're a developer or contributor to Ghost, you should test this release in a development environment to help identify any issues with the new boot process, database schema changes, or API version migration.

For theme developers, testing your themes with this release would be valuable to ensure compatibility with the updated social media metadata handling and content helper changes.

Wait for the stable 4.0.0 release before upgrading production sites.

Bug Fixes

Fixed Member Model Label Handling

Fixed an issue where the Member model was incorrectly removing labels when they were unset. The bookshelf-relations plugin was removing all relations when set to an empty array, but leaving them alone when undefined. The fix ensures that label handling is skipped when no labels are set.

Fixed Gmail Newsletter Display Issues

• Fixed a bug where newsletter bookmark cards weren't displaying correctly in Gmail
• Fixed a bug for newsletter bookmarks without author displaying redundant separator

Fixed Settings Validation Error Messages

When saving Stripe keys with stripeDirect: true config, validation errors now correctly distinguish between publishable and secret keys, showing the appropriate error message for each.

New Features

New Linear Boot Process

A completely redesigned boot process has been introduced to simplify Ghost's startup sequence. This new approach is more linear and easier to follow, making it possible to decouple Ghost into smaller components in the future. The process includes a standalone database migration utility and clearer separation of concerns.

Member Subscription Event Tracking

Added a new members_subscribe_events table and corresponding model to track member subscription events. This feature allows for better analytics on when members subscribe and unsubscribe, including historical data through backfilling.

Enhanced Social Media Metadata

Improved Twitter/OG structured data rules with a clearer fallback hierarchy:

• Post/page Twitter image falls back to: post.twitter_image → post.feature_image → settings.twitter_image → settings.cover_image
• Post/page OG image falls back to: post.og_image → post.feature_image → settings.og_image → settings.cover_image

Slug + Type Unique Constraint

Changed the unique constraint in the posts table from just slug to slug+type, allowing posts and pages to have the same slug. This constraint will be enforced at the application layer for API v4 while planning for API v5.

Security Updates

No specific security fixes were mentioned in this release.

Performance Improvements

Database Schema Improvements

• Added unique constraint notation to schema definition with @@UNIQUE_CONSTRAINTS@@ to create constraints over multiple database fields
• Refactored the createTable migration utility to remove unnecessary lodash dependency and simplify the code
• Added optional tableSpec parameter to addTable utility to make migrations more self-contained

Dependency Updates

Multiple dependency updates to improve performance and security:

• Updated @sentry/node to v6.1.0
• Updated nconf to v0.11.2
• Removed oembed-parser from overrides as it no longer depends on promise-wtf
• Updated various Ghost packages to their latest versions

Impact Summary

Ghost 4.0.0-alpha.1 represents a significant architectural shift with its new linear boot process, laying the groundwork for future decoupling of Ghost components. This will eventually lead to a more modular and maintainable codebase.

The database schema changes, particularly the new unique constraint on slug+type rather than just slug, provide more flexibility for content creators who want to use the same slug for both posts and pages.

The improved social media metadata handling ensures better representation of content when shared on platforms like Twitter and Facebook, with a more logical fallback system.

Member subscription event tracking adds valuable analytics capabilities, allowing site owners to better understand subscriber behavior over time.

While this alpha release introduces breaking changes, they're part of a deliberate evolution toward a more robust and flexible platform. The migration to API v3 as the default continues Ghost's pattern of progressive enhancement while maintaining backward compatibility through explicit versioning.

Full Release Notes