So, to help me acclimate to the role, I decided to analyze a few hundred top ranking webpages on growth engineering topics and extract out the most commonly used phrases into a Glossary format.

Below is a curated version of the output and terms I found helpful, and a helpful outline/mental structure for thinking about grouping these topics.

Table of Contents

• Methodology and Process Terms
• Role Titles and Team Structures
• A/B Testing and Experimentation Vocabulary
• Feature Flags and Rollout Terminology
• Growth Loops and Growth Model Terminology
• Network Effects Terminology
• Viral Mechanics and Referral Terminology
• PLG (Product-Led Growth) Terminology
• Activation, Retention, and Engagement Metrics
• Churn Terminology
• Funnel Optimization Language
• AARRR Pirate Metrics Framework
• Onboarding and User Journey Phrases
• Technical Growth Infrastructure Terms
• Attribution and Analytics Terminology
• Mobile Attribution Terms
• Identity and User Identification Terms
• Monetization and Conversion Optimization Language
• Pricing Optimization Terms
• North Star Metrics and Goal-Setting Vocabulary
• SaaS and Revenue Metrics
• Key benchmarks reference
• Sources consulted
• Methodology

Methodology and Process Terms

Growth Engineering — The systematic, technical approach to growth using data-driven experiments rather than gut-driven decisions. Often described as "writing code to make a company money." [Eric Feng] [Pragmatic Engineer]

Build to Learn — Growth engineering philosophy where code is shipped primarily to learn and validate hypotheses, not to build lasting features. Contrasts with product engineering's "build to last" approach. [Alexey MK]

Kill Your Darlings — Growth engineering mindset of willingness to throw away failed experiments without attachment, essential for rapid iteration. [Alexey MK]

Hypothesis-Driven Development — Approach where features and experiments are designed around testable hypotheses with clear success criteria. [Atlassian]

Experiment Roadmap — Prioritized backlog of growth experiments separate from the product roadmap. [Productboard]

RICE Framework — Prioritization framework: Reach × Impact × Confidence ÷ Effort. Used to prioritize growth experiments. [Product School]

ICE Framework — Simplified prioritization: Impact × Confidence × Ease, scored 1-10 for each factor. [CXL]

Fake Door Test — Offering a not-yet-available feature to gauge customer interest before investing in full development. [ProdPad]

Tent vs Skyscraper — Metaphor for growth vs product engineering approaches. Tents (growth) optimize for speed of setup/teardown; skyscrapers (product) optimize for durability and permanence. [Alexey MK]

Growth Engineering vs Product Engineering — Product engineers build core product features for longevity; growth engineers optimize business metrics through rapid experimentation. [Pragmatic Engineer]

Growth Engineering vs Marketing Engineering — Marketing engineers serve internal teams and focus on productivity tools. Growth engineers focus on business metrics and customer-facing optimization. [Pragmatic Engineer]

Role Titles and Team Structures

Growth Engineer — A software engineer who combines technical expertise with data-driven strategies to drive user acquisition, engagement, and revenue growth. Unlike product engineers who build features for longevity, growth engineers optimize business metrics through rapid experimentation. Origins trace to Facebook in 2007 under Chamath Palihapitiya. [Pragmatic Engineer] [UserGuiding]

Growth PM (Growth Product Manager) — A product manager responsible for improving specific business metrics rather than owning a specific product area. Focuses on short-term experiments across the entire user funnel—from acquisition through monetization. [ProductLed] [Userpilot]

Growth Hacker — Marketing-oriented role focused on creative, low-cost strategies for customer acquisition. Coined by Sean Ellis in 2010. Relies on non-technical solutions and shortcuts, unlike growth engineers who use systematic, technical approaches. [Medium]

Growth Designer — Designer within growth teams who creates user interfaces optimized for engagement and conversion. Works closely with growth engineers on A/B test variations and rapid experimentation. [Productboard]

Growth Data Analyst / Product Analyst — Data specialists who dive deep into user data, extract insights, decode behavior patterns, monitor KPIs, and provide actionable recommendations to inform growth strategy. [Productboard]

Technical Growth Marketer — Marketer who understands backend development, APIs, and script building. Bridges the gap between marketing and engineering. [Pragmatic Engineer]

VP of Growth / Head of Growth — Executive responsible for overall growth strategy, team structure, and organizational alignment. [Andrew Chen]

Chief Growth Officer (CGO) — Executive position leading growth teams; responsible for setting strategy, goals, and tasks across all growth initiatives. [Mixpanel]

Growth Team — Cross-functional team dedicated to driving user acquisition, engagement, and retention. Typically includes engineers, PMs, designers, data analysts, and sometimes marketers. [Product School] [CXL]

Independent Growth Team — Standalone team with its own PM, engineers, designers, and analysts functioning as a "mini startup" within the company. [Andrew Chen]

Embedded Growth Function — Growth specialists who sit within core product teams and own specific metrics. [CXL]

Hybrid Growth Model — Combination of independent and embedded approaches; adapts to company needs and scales with organizational growth. [Product School]

Growth Pod — Small, focused team carved out to work full-time on key growth initiatives. [Mixpanel]

Owner Model — Growth team structure where growth engineering operates independently with full ownership of their domain and metrics. [Pragmatic Engineer]

Hitchhiker Model — Growth engineers who work alongside other product teams, contributing growth expertise while those teams retain primary ownership. [Pragmatic Engineer]

A/B Testing and Experimentation Vocabulary

A/B Testing (Split Testing) — Core growth engineering methodology comparing two versions (control vs. variant) to measure which performs better on specific metrics. [ProdPad] [Netflix Tech Blog]

Control Group — The group of users that sees the original, unchanged version of the experience. Serves as the baseline for comparison. [Mida]

Treatment (Variant) — The new or modified version of the experience being tested against the control. [Mida]

A/B/n Test — A variation of A/B testing where multiple variants (n) are tested against a control simultaneously. [VWO]

A/A Test — An experiment where identical versions are tested against each other to validate the testing framework and ensure there are no systemic biases. [BigDATAwire]

Multivariate Test (MVT) — An experiment that tests multiple variables and their combinations simultaneously to determine which combination produces the best outcome. [Braze]

Holdout Group — A subset of users deliberately excluded from receiving new features to serve as a long-term baseline for measuring cumulative impact. [Netflix/SlideShare]

Statistical Significance — An indicator that the observed difference between control and treatment groups is unlikely to have occurred by random chance alone. Typically measured at 95% confidence level (α = 0.05). [Mida]

P-value — The probability of observing results as extreme or more extreme than the observed results, assuming the null hypothesis is true. [Mida]

Confidence Level — The level of certainty (e.g., 95%) that the true effect lies within the confidence interval. [Mida]

Confidence Interval — The range of values within which the true metric value is likely to fall if the experiment were repeated many times. [Mida]

Minimum Detectable Effect (MDE) — The smallest true effect size that an A/B test can reliably detect with specified statistical power. [BigDATAwire]

Statistical Power — The probability that an experiment will correctly detect a real effect as statistically significant when it exists. Convention is 80% power. [Mida]

Type I Error (False Positive) — Incorrectly rejecting the null hypothesis when there is actually no real effect. [Mida]

Type II Error (False Negative) — Failing to reject the null hypothesis when a real effect actually exists. [Mida]

Null Hypothesis — The assumption that there is no significant difference between the control and treatment groups. [Mida]

Sample Size — The number of visitors or users included in an experiment. Larger samples increase power and enable detection of smaller effects. [Mida]

Lift — The percentage improvement in a metric between the treatment and control groups. Calculated as (Treatment - Control) / Control × 100%. [Mida]

Primary Metric (Success Metric) — The central metric that the experiment aims to optimize, directly tied to business goals. [VWO]

Guardrail Metric — Secondary metrics monitored during experiments to ensure changes don't have unintended negative consequences. [Eppo] [VWO]

Diagnostic Metric — Metrics providing deeper insight into how an experiment affected user behavior beyond the primary success metric. [VWO]

CUPED (Controlled-experiment Using Pre-Experiment Data) — A variance reduction technique using pre-experiment data to reduce noise and accelerate experiment results by 20-65%. [BigDATAwire]

Sequential Testing — A method allowing data analysis at multiple points during an experiment while maintaining statistical validity. [Mida]

Bayesian Inference — A statistical approach using prior beliefs updated with observed data to calculate probability distributions of effects. [Mida]

Frequentist Statistics — The traditional statistical framework using fixed hypothesis testing, p-values, and confidence intervals. [Mida]

Bonferroni Correction — A statistical adjustment reducing false-positive rates when conducting multiple hypothesis tests. [Mida]

Multi-Armed Bandit (MAB) — An adaptive algorithm that dynamically allocates traffic to better-performing variants in real-time. [VWO] [Wikipedia]

Thompson Sampling — A Bayesian bandit algorithm that samples from posterior distributions to determine which variant to show. [Braze]

Contextual Bandit — An advanced MAB that uses context about users, variants, and environment to make personalized allocation decisions. [Braze]

Sample Ratio Mismatch (SRM) — A diagnostic check detecting when actual traffic split differs significantly from intended allocation. [BigDATAwire]

Stratified Sampling — Random distribution with enforcement of sample proportions across segments to ensure representative allocation. [Mida]

Novelty Effect — A temporary change in user behavior due to the newness of a feature, which may fade over time. [Mida]

Primacy Effect — Users preferring original experiences due to familiarity, potentially biasing results against new variants. [Mida]

Winner's Curse — The phenomenon where winning variants' effects appear inflated when measured individually. [Mida]

Experiment Velocity — The rate at which an organization can run experiments, often measured in experiments per week or month. [Pragmatic Engineer]

Overall Evaluation Criterion (OEC) — A composite metric combining multiple signals into a single measure for experiment decision-making. [Netflix Tech Blog]

Feature Flags and Rollout Terminology

Feature Flag — A software development technique that enables or disables features without code deployment, allowing controlled feature releases and experiments. [Pragmatic Engineer]

Progressive Rollout (Percentage Rollout) — Gradually increasing the percentage of users exposed to a feature over time (e.g., 10% → 25% → 50% → 100%).

Kill Switch — An emergency feature flag that can instantly disable a feature if problems are detected.

Targeting Rules — Logic determining which users see which flag variation based on attributes like user properties, device type, or location.

Fallthrough (Default Rule) — The rule applied when no specific targeting conditions match.

Release Flag (Rollout Flag) — A temporary boolean flag used to control incremental feature releases.

Experiment Flag — A feature flag specifically configured for A/B testing, often with multiple variations and associated metrics.

Canary Release (Canary Test) — Releasing a change to a small subset of users before broader rollout to detect issues early.

Dark Launch — Deploying code to production without exposing it to users, enabling testing of infrastructure before feature activation.

Bucketing — The process of assigning users to experiment variants, typically using consistent hashing of user identifiers.

Exposure — The moment when a user is shown a variant and their assignment is logged for analysis.

Growth Loops and Growth Model Terminology

Growth Loop — A closed system where inputs go through a series of pre-defined steps to generate outputs, which are then reinvested as new inputs. Unlike linear funnels, loops compound over time. Reforge popularized this framework. [Ortto]

Viral Loop — A mechanism where users refer others to a product, and those referrals become referrers through the same mechanism, creating a self-reinforcing cycle. [Ortto]

Content Loop — A growth loop where content creation and distribution attracts users who then create more content. Can be user-generated (Pinterest) or company-generated (HubSpot). [Ortto]

Paid Loop — A growth loop where paid advertising attracts users/customers, generating revenue that can be reinvested into more paid advertising. [Ortto]

Sales Loop — A loop where a sales force acquires customers, generating revenue that funds hiring more salespeople. [Ortto]

Acquisition Loop — Any loop focused specifically on bringing new users into the product.

Loop Velocity — The speed at which a growth loop completes one full cycle. Faster velocity means faster compounding growth.

Loop Efficiency — A measure of how much output a loop generates relative to its inputs.

K-Factor (Viral Coefficient) — The number of new users each existing user generates through invitations or referrals. Formula: K = i (invites sent per user) × c (conversion rate of invites). A K-factor >1 indicates exponential growth. [Yotpo]

Viral Cycle Time — The time from a user joining to successfully referring a new user who joins. Shorter cycle times accelerate viral growth. [Yotpo]

Compounding Growth — Growth that builds upon itself over time, creating exponential rather than linear growth curves.

Critical Mass — The minimum number of users required for a network or viral effect to become self-sustaining.

Growth Flywheel — A framework visualizing growth as a circular, self-reinforcing system rather than a linear funnel. [Chameleon]

Flywheel Friction — Anything that slows down the flywheel's momentum—poor onboarding, confusing pricing, bad UX. [Chameleon]

Network Effects Terminology

Network Effect — When a product becomes more valuable as more people use it. Responsible for 70% of value created by tech companies since 1994.

Direct Network Effect — When increased usage directly increases value to users (e.g., telephone networks—more users = more people to call).

Indirect Network Effect — When increased usage of one side increases value for a different side (e.g., more iOS users = more apps developed).

Two-Sided Network Effect — Networks with two distinct user groups (supply and demand) that provide complementary value to each other.

Data Network Effect — When product value increases with more data, and usage generates more useful data.

Metcalfe's Law — The value of a network is proportional to the square of the number of users (N²).

Reed's Law — Network value increases exponentially (2^N) as sub-groups can form within the network.

Marketplace Network Effect — Two-sided effect where buyers attract sellers and sellers attract buyers.

Platform Network Effect — Supply side engineers products specifically for the platform (e.g., iOS app developers).

Asymptotic Network Effect — When initial supply quickly adds value but additional supply yields diminishing returns.

Multi-tenanting — When users can participate in multiple competing networks simultaneously, weakening network lock-in.

Market Tipping — When one network gains enough advantage that it "pulls away" from competitors.

Bandwagon Effect — Social pressure to join a network to avoid being "left out."

Network Density — The number of connections between nodes in a network. Higher density = more valuable network.

Viral Mechanics and Referral Terminology

Referrer/Advocate — The existing customer who recommends a product to others and earns rewards for successful referrals. [Yotpo]

Referee/Referred Friend — The new customer who discovers a brand based on an advocate's recommendation. [Yotpo]

Double-Sided Incentive (Give X, Get Y) — A referral structure where both the referrer and the referred friend receive rewards. [Yotpo]

Referral Link/Code — A unique identifier assigned to each referrer for tracking successful referrals and attributing rewards. [Yotpo]

Referral Loop — The complete cycle: advocate makes purchase → joins program → shares link → friend converts → both get rewards → friend becomes advocate. [Yotpo]

Invite Mechanics — The system design for how users invite others—including invite prompts, sharing channels, friction reduction, and timing.

Referral Rate — The percentage of users who successfully refer at least one new user within a given time period.

Share Rate — The percentage of users who share referral links, regardless of conversion outcome.

Tiered Referral Program — A system offering increasingly valuable rewards as advocates refer more customers. [Yotpo]

Inherent Virality — When the product's core use case naturally involves sharing (e.g., Calendly sends invites by its nature) versus engineered virality through incentives.

Word-of-Mouth (WOM) — Organic sharing and recommendations between people.

Social Proof — The psychological phenomenon where people look to others' actions to determine their own.

PLG (Product-Led Growth) Terminology

Product-Led Growth (PLG) — A business methodology where user acquisition, expansion, conversion, and retention are all driven primarily by the product itself rather than sales or marketing. Coined by OpenView's Blake Bartlett in 2016. [Chameleon]

Product Qualified Lead (PQL) — A lead who has experienced the product's value firsthand (via free trial or freemium) and demonstrated buying intent through product usage behaviors. [Chameleon]

Product Qualified Account (PQA) — The account-level equivalent of a PQL for B2B, identifying high-value sales opportunities based on collective usage patterns.

Time to Value (TTV) — The time it takes for a user to realize meaningful value from the product after first use. [ProductLed]

Time to First Value (TTFV) — Specifically measures the time until a user experiences the initial benefit.

Self-Serve — A go-to-market model where users can discover, evaluate, adopt, and purchase the product without requiring sales assistance.

Freemium — A pricing model offering free access to basic features, with paid upgrades for premium functionality.

Free Trial — A time-limited full access model that lets users experience the complete product before committing to purchase.

Reverse Trial — A model where users start with full premium features, then downgrade to free tier after the trial ends.

PQL Rate — The percentage of new signups reaching PQL status.

PQL to Paid Conversion Rate — The percentage of PQLs who convert to paying customers.

Time to PQL — How long it takes a user to reach PQL status.

Product-Led Sales (PLS) — A hybrid approach combining PLG's bottom-up motion with traditional top-down sales, using product usage data to identify sales opportunities.

Value Metric — The unit of measure that aligns pricing with customer value (e.g., number of users, messages sent, storage used).

Bottom-Up Adoption — When end users adopt a product independently, then drive organizational adoption.

Land and Expand — Strategy of starting small within an organization (land) then growing usage and revenue within that account over time (expand).

PLG Flywheel Stages

Evaluator — First stage user exploring whether the product might solve their problem. [Chameleon]

Beginner — User who has started using the product but hasn't activated. [Chameleon]

Regular — Activated user who has adopted the product into their workflow. [Chameleon]

Champion — Highly engaged user invested in the product's success who becomes an advocate. [Chameleon]

Activate → Adopt → Adore → Advocate — The PLG Flywheel action sequence connecting user stages. [Chameleon]

Activation, Retention, and Engagement Metrics

Aha Moment — The pivotal point when a user suddenly realizes and experiences the core value of a product. Examples: Facebook's 7 friends in 10 days, Twitter's following 30 people, Slack's 2,000 messages exchanged. [Amplitude]

Activation — The process of turning new sign-ups into engaged users who clearly understand and experience product value. [ProductLed]

Activation Rate — The percentage of users who complete a defined activation milestone. Industry average for SaaS is approximately 37.5%.

Activation Event — A specific, measurable action that signifies a user has experienced product value.

Activation Velocity — A metric measuring how quickly a cohort of users activates over time. [ProductLed]

Setup Moment — The point when users complete essential configuration steps that enable them to derive value.

Daily Active Users (DAU) — The number of unique users who engage with a product within a 24-hour period. [Geckoboard]

Weekly Active Users (WAU) — The number of unique users who engage with a product over a 7-day period.

Monthly Active Users (MAU) — The number of unique users who engage with a product over a 30-day period. [Geckoboard]

DAU/MAU Ratio (Stickiness) — The proportion of monthly active users who engage daily. Standard benchmark is 10-25%; top apps like WhatsApp exceed 50%. [Geckoboard] [Gainsight]

Stickiness — How often users return to engage with a product. A sticky product becomes part of users' daily routines. [Wall Street Prep]

Retention Rate — The percentage of users who continue engaging with a product over a specific time period. [Amplitude]

Retention Curve — A visual representation showing how user retention changes over time, typically declining before reaching an asymptote. [Amplitude]

Retention Asymptote — The point where a cohort's retention curve flattens, indicating the percentage of users expected to remain long-term.

N-Day Retention — Retention measured at specific intervals after sign-up (Day 1, Day 7, Day 30, etc.). [Adjust]

Rolling Retention — Measures users who return on or after a specific day, rather than on that exact day.

Cohort — A group of users who share a common characteristic tracked together over time. [Headline]

Cohort Analysis — A method of grouping users by shared characteristics and tracking their behavior over time. [Medium]

Acquisition Cohort — Users grouped by when they were acquired (e.g., all January sign-ups). [Amplitude]

Behavioral Cohort — Users grouped by actions they've taken within the product. [Amplitude]

Power Users — The most engaged segment of users who use the product frequently and deeply.

Churn Terminology

Churn Rate — The percentage of customers who stop using a product or cancel subscriptions during a given period. [ChurnZero]

Customer Churn (Logo Churn) — The number/percentage of customers lost, regardless of their revenue value. [ChurnZero]

Revenue Churn (MRR/ARR Churn) — The amount of recurring revenue lost due to cancellations and downgrades. [Mercury]

Gross Churn — Revenue lost from churned customers without accounting for expansion revenue. [Mercury]

Net Churn — Revenue lost minus revenue gained from existing customer expansions. Negative net churn is positive. [Mercury]

Voluntary Churn — When customers intentionally choose to cancel or not renew. [Younium]

Involuntary Churn — Customer loss due to payment failures or other non-intentional reasons. [SaaS Academy]

Churn Cohort Analysis — Grouping customers by acquisition time to analyze churn behavior patterns.

Funnel Optimization Language

Conversion Funnel (Sales Funnel/Marketing Funnel) — A visualization of the steps users take from awareness to completing a desired action.

TOFU (Top of Funnel) — The awareness stage where prospects first discover a product.

MOFU (Middle of Funnel) — The consideration stage where prospects evaluate whether a product fits their needs.

BOFU (Bottom of Funnel) — The decision stage where prospects are ready to convert/purchase.

AIDA Model — Attention, Interest, Desire, Action—a classic marketing framework describing customer journey stages.

Conversion Rate — The percentage of users who complete a desired action out of total users at a funnel stage.

Drop-off Rate — The percentage of users who abandon the funnel at a specific step.

Funnel Friction — Any obstacle, confusion, or unnecessary step that causes users to abandon the funnel.

Friction Point — A specific moment in the user journey where users struggle or abandon the process.

Micro-Conversion — Small, interim actions users take on the way to a macro-conversion (e.g., adding to cart before purchase).

Macro-Conversion — The primary goal action (e.g., purchase, subscription sign-up).

Funnel Analysis — Tracking user progression through sequential steps toward a goal, identifying drop-off points. [Medium]

AARRR Pirate Metrics Framework

AARRR (Pirate Metrics) — Dave McClure's 2007 framework tracking five user-behavior metrics: Acquisition, Activation, Retention, Referral, Revenue. Called "pirate metrics" because the acronym sounds like "Arrr!" [Built In]

Acquisition — First stage; how users discover the product. [Built In]

Activation — Second stage; user's first valuable experience with product. [Built In]

Retention — Third stage; keeping users engaged and returning. [Built In]

Referral — Fourth stage; users recommending product to others. [Built In]

Revenue — Fifth stage; monetizing user engagement. [Built In]

RARRA Framework — Alternative framework prioritizing Retention first: Retention, Activation, Referral, Revenue, Acquisition.

Onboarding and User Journey Phrases

User Onboarding — The process of acquainting new users with a product, guiding them from sign-up to activation. [Userpilot]

Onboarding Flow — A step-by-step sequence introducing users to a product's features and value. [Userpilot]

Primary Onboarding — Initial onboarding focused on core features and getting users to their first aha moment. [The User Flow]

Secondary Onboarding — Introducing users to advanced features building on core value. [The User Flow]

Tertiary Onboarding — Account expansion focused on upselling additional features.

Product Tour — A guided walkthrough introducing users to product features and interface. [Appcues]

Interactive Walkthrough — Hands-on guidance where users learn by performing actions within the product.

Onboarding Checklist — A list of tasks guiding users through setup and initial product engagement. [Userpilot]

Progress Bar — A visual indicator showing users how far they've progressed through onboarding.

Empty State — The initial state of a product interface before users add data, often used to provide guidance.

Welcome Survey — A questionnaire during sign-up collecting user preferences to personalize onboarding.

Persona-Based Onboarding — Customizing onboarding flows based on user type, role, or goals.

Progressive Disclosure — Gradually revealing product features to avoid overwhelming new users.

Deferred Account Creation — Postponing registration until users have experienced product value.

Gradual Engagement — Allowing users to experience value before requiring commitment.

Onboarding Completion Rate — Percentage of users who finish the onboarding process.

Tooltip — A contextual hint appearing when users hover over or click UI elements.

Hotspot — A pulsing indicator drawing attention to specific features or actions.

Modal — A pop-up window requiring user attention or action.

Slideout — A panel that slides in from the screen edge with information or prompts.

Auth vs Unauth — Authenticated versus unauthenticated user experiences; different optimization strategies apply to logged-in users versus anonymous visitors. [Pragmatic Engineer]

Technical Growth Infrastructure Terms

Growth Stack — Collection of tools and technologies used by growth teams for analytics, experimentation, automation, and optimization.

Experiment Platform — Infrastructure for standardizing A/B test setup, user bucketing, and statistical methodology. [Netflix Tech Blog]

MarTech (Marketing Technology) — Tools enabling marketers to work without engineering involvement: landing page builders, email platforms, analytics tools.

Customer Data Platform (CDP) — Software that collects, unifies, and activates customer data from multiple sources to create persistent, unified customer profiles. Examples: Segment, mParticle, Rudderstack.

Data Management Platform (DMP) — A platform focused on third-party data for advertising audience targeting.

Event — A discrete user action or system occurrence tracked in analytics (e.g., page_view, button_click, purchase).

Event Properties — Metadata attached to events providing additional context.

User Traits — Attributes stored on user profiles that persist across sessions.

Event Streaming — Real-time continuous transmission of event data as it occurs.

Event Broker (Event Bus) — Infrastructure (e.g., Apache Kafka) that receives, stores, and distributes event streams.

ETL (Extract, Transform, Load) — Traditional data pipeline pattern for data movement and transformation.

ELT (Extract, Load, Transform) — Modern pattern where raw data is loaded directly into a data warehouse, then transformed.

Data Pipeline — Automated system for moving data from source systems through processing stages to destinations.

Reverse ETL — Moving data from a data warehouse back to operational tools for activation.

Data Warehouse — Centralized repository optimized for analytical queries on historical data.

Change Data Capture (CDC) — Technology that detects and captures changes in source databases for real-time synchronization.

Instrumentation — The process of adding tracking code to applications to capture user behavior events.

Tracking Plan — Documentation specifying which events and properties to track, their definitions, and implementation requirements.

Event Taxonomy — The naming conventions, hierarchy, and structure for organizing tracked events consistently.

Auto-Capture (Auto-Track) — Automated collection of user interactions without manual event instrumentation.

Device Mode (Client-Side) — Analytics implementation where tracking libraries load directly on user devices.

Cloud Mode (Server-Side) — Analytics implementation where data is sent to your servers first, then forwarded to destinations.

Attribution and Analytics Terminology

Multi-Touch Attribution (MTA) — A measurement technique that assigns fractional credit to multiple touchpoints along the customer journey.

Last-Touch Attribution — An attribution model that assigns 100% credit to the final touchpoint before conversion.

First-Touch Attribution — An attribution model giving 100% credit to the first marketing touchpoint.

Linear Attribution — A multi-touch model that distributes equal credit across all touchpoints.

Time Decay Attribution — A model assigning progressively more credit to touchpoints occurring closer to conversion.

U-Shaped Attribution (Position-Based) — Assigns 40% credit each to first and last touchpoints, with 20% distributed across middle interactions.

W-Shaped Attribution — Gives 30% credit each to first touch, lead creation, and opportunity creation touchpoints.

Data-Driven Attribution (Algorithmic) — Uses machine learning to dynamically assign credit based on actual conversion path data.

View-Through Attribution — Credits conversions to ad impressions that were viewed but not clicked.

Click-Through Attribution — Credits conversions only to ads that were actually clicked.

Attribution Window (Lookback Window) — The time period during which touchpoints are considered eligible for attribution credit.

UTM Parameters (Urchin Tracking Module) — URL tags added to links to track marketing campaign performance.

utm_source — Identifies the traffic source (e.g., google, facebook, newsletter).

utm_medium — Identifies the marketing medium/channel type (e.g., cpc, email, social).

utm_campaign — Identifies the specific campaign name or promotion.

utm_content — Differentiates between similar content or links within the same campaign.

utm_term — Identifies paid search keywords driving traffic.

Tracking Pixel — A 1x1 transparent image embedded in web pages or emails that fires an HTTP request when loaded.

Incrementality Testing — Controlled experiments measuring the true causal impact of marketing.

Marketing Mix Modeling (MMM) — Statistical analysis evaluating the aggregate impact of marketing spend across channels.

Mobile Attribution Terms

Mobile Measurement Partner (MMP) — A third-party platform that attributes app installs and in-app events to marketing sources. Examples: AppsFlyer, Adjust, Branch, Singular.

IDFA (Identifier for Advertisers) — Apple's device-level identifier for tracking and attribution on iOS.

GAID (Google Advertising ID) — Google's device-level identifier for Android devices.

SKAdNetwork (SKAN) — Apple's privacy-preserving attribution framework providing aggregated, anonymized conversion data.

Deterministic Attribution — Attribution method using exact identifier matches for high-confidence attribution.

Probabilistic Attribution (Fingerprinting) — Statistical method using device characteristics and behavioral patterns for attribution.

Deep Linking — Technology that routes users to specific in-app content rather than just opening an app.

Deferred Deep Linking — Deep linking that works even when the app isn't installed.

Self-Reporting Network (SRN) — Major ad platforms (Meta, Google, TikTok) that perform their own attribution.

Install Referrer — Data passed from app stores containing attribution information about where an app install originated.

Identity and User Identification Terms

Anonymous ID (anonymousId) — A UUID automatically generated for unknown visitors before they authenticate.

User ID (userId) — A persistent, unique identifier assigned to users after they authenticate.

Device ID — A unique identifier tied to a specific device.

Client ID — Browser-specific identifier generated by analytics tools to identify unique browser sessions.

Identity Resolution — The process of connecting multiple identifiers to create unified user profiles across devices and sessions.

Identity Graph — A data structure that maps relationships between different user identifiers.

Identity Stitching — The process of merging previously anonymous user sessions with identified user profiles.

Cross-Device Tracking — The ability to recognize and track the same user across multiple devices.

Monetization and Conversion Optimization Language

CTA (Call-to-Action) — A button, link, or prompt that encourages users to take a specific action.

Friction — Any element that creates resistance or hesitation in the user journey, reducing conversion likelihood.

Bounce Rate — The percentage of visitors who leave a site after viewing only one page without taking action.

Heatmap — A visual representation of user behavior showing where visitors click, scroll, and focus attention.

Session Replay — Recordings of individual user sessions showing exactly how visitors navigate and interact.

Above the Fold — Content visible on a webpage without scrolling.

Social Proof — Evidence that others have used/endorsed a product (testimonials, reviews, logos, user counts).

Paywall — A barrier restricting content/feature access until users pay.

Hard Paywall — All features locked behind payment/subscription after optional free trial.

Soft Paywall — Some features available free while premium features require payment.

Metered Paywall — Users get limited free access (e.g., 3 articles/month) before hitting the paywall.

Dynamic Paywall — Adjusts access based on user behavior, engagement level, or segment in real-time.

Feature Gating — Restricting specific features to paid tiers to drive upgrade behavior.

Usage-Based Pricing — Pricing tied to consumption/usage metrics rather than flat subscriptions.

Tiered Pricing — Multiple pricing levels targeting different user segments and willingness to pay.

Pricing Optimization Terms

Price Elasticity — How demand changes in response to price changes. Elastic demand (>1) = highly responsive; Inelastic (<1) = low sensitivity.

Willingness to Pay (WTP) — The maximum price a customer will pay for a product/feature.

Van Westendorp Price Sensitivity Meter — Survey technique asking four questions about price thresholds to identify optimal price range.

Gabor-Granger Method — Price research technique presenting different price points to measure purchase likelihood.

Conjoint Analysis — Research method presenting product configurations at varying prices to reveal how features impact willingness to pay.

Value-Based Pricing — Setting prices based on perceived customer value rather than cost-plus or competitor pricing.

Price Anchoring — Psychological technique showing expensive options first to make lower tiers appear more reasonable.

Annual Discount — Offering reduced rates for annual commitment (typically 20-30% off monthly equivalent).

North Star Metrics and Goal-Setting Vocabulary

North Star Metric (NSM) — A single, company-wide metric that best captures the core value delivered to customers. Examples: Airbnb's "Nights Booked," Spotify's "Time Spent Listening." [Amplitude]

Input Metrics — The contributing factors that influence a North Star Metric. Common dimensions: breadth (reach), depth (engagement), frequency (cadence), efficiency. [Amplitude]

Output Metrics — Business outcomes that result from North Star Metric improvements (revenue, profit, market share).

OKRs (Objectives and Key Results) — A goal-setting framework where Objectives are qualitative goals, and Key Results are specific, measurable outcomes.

Committed OKRs — Goals the organization must achieve; expected to reach 100% completion.

Aspirational OKRs — Stretch goals aimed at significant progress; 70% achievement is considered successful.

One Metric That Matters (OMTM) — A team-specific focus metric that changes quarterly based on current priorities.

KPIs (Key Performance Indicators) — Quantitative metrics pegged to specific targets used to measure success.

Leading Indicators — Metrics that predict future outcomes and provide early warning signals.

Lagging Indicators — Metrics that measure past performance/outcomes.

SaaS and Revenue Metrics

MRR (Monthly Recurring Revenue) — Predictable monthly revenue from subscriptions.

ARR (Annual Recurring Revenue) — MRR × 12; the key metric for company valuation.

New MRR — Recurring revenue from newly acquired customers in a period.

Expansion MRR — Additional revenue from existing customers through upgrades or add-ons.

Churned MRR — Revenue lost from customers who cancelled during a period.

Contraction MRR — Revenue reduction from existing customers downgrading plans.

Net Revenue Retention (NRR/NDR) — Revenue retained from existing customers including expansion minus churn/contraction. Over 100% indicates net negative churn.

Gross Revenue Retention (GRR) — Revenue retention excluding expansion; measures pure retention capability.

LTV (Customer Lifetime Value) — Total revenue expected from a customer over their entire relationship.

CAC (Customer Acquisition Cost) — Total cost to acquire one new customer, including marketing and sales expenses.

LTV:CAC Ratio — Compares customer lifetime value to acquisition cost. Benchmark: 3:1.

CAC Payback Period — Months required to recover customer acquisition cost.

ARPU/ARPA (Average Revenue Per User/Account) — Total MRR divided by total customers.

ACV (Annual Contract Value) — Annual value of a customer's subscription revenue.

Trial-to-Paid Conversion — Percentage of free trial users who convert to paying customers.

Quick Ratio (SaaS) — Measures growth efficiency: (New MRR + Expansion MRR) ÷ (Churned MRR + Contraction MRR). Benchmark: 4:1.

Unit Economics — The direct revenues and costs associated with a single customer.

NPS (Net Promoter Score) — Customer satisfaction measure based on likelihood to recommend (-100 to +100 scale).

Feature Adoption Rate — Percentage of users who adopt and use a specific feature.

Product Adoption Rate — Percentage of new active users relative to sign-ups over a specific period.

Key benchmarks reference

Sources consulted

This glossary draws terminology from authoritative sources including:

• Engineering blogs from Airbnb, Netflix, Uber, Pinterest, and Dropbox
• Growth methodology content from Reforge, OpenView, and ProductLed
• Analytics platforms including Amplitude, Mixpanel, Segment, and Heap
• Experimentation platforms such as Statsig, LaunchDarkly, Optimizely, and GrowthBook
• Attribution platforms including AppsFlyer, Adjust, and Branch
• SaaS metrics resources from ChartMogul, ProfitWell, and Baremetrics
• Growth-focused publications including Lenny's Newsletter, First Round Review, and CXL

Methodology

I used Claude in deep research mode to build the initial framework for this page in 2025 and have expanded and updated it manually since. Here's a sample of the starting prompt used if you'd like to replicate this for another topic area.

Generate a long list of phrases used in articles and webpages talking about "growth engineer" or "growth engineering" and output it as a glossary type of format please.

Eg "auth vs unauth experience"

Review as many URLs as you can and do a query fan out on those keywords to dive into various sub topics.

How to Delete Local Branches That Have Been Deleted From Github / Origin

Nowadays in my repos I configure Github to "Automatically delete head branches" after we squash and merge. But I didn't used to do that before the feature existed, so we have a lot of branches hanging around on Github that could be deleted.

But as far as I can tell, those branches still stick around on my local device.

So this first command deletes all local branches that no longer exist on origin, except for my current branch:

git fetch -p && git branch -vv | grep ': gone]' | awk '{print $1}' | xargs -I {} git branch -D {}

It shouldn't delete:

1. Local-only branches — branches you created but never pushed
2. Branches still on origin — even if you don't care about them locally, if they exist remotely, they're kept
3. Your current branch — git won't let you delete the branch you're on

Since this is one I'll run periodically moving forward, I've also set it up as a zsh alias in my .zshrc file.

# git helpers
alias cleanbranches="git fetch -p && git branch -vv | grep ': gone]' | awk '{print $1}' | xargs -I {} git branch -D {}"

How to Delete Github / Origin Branches That Aren't Attached to PRs

Now - we used to not automatically delete branches on squash and merge. So that means we also have a ton of historical branches on Github (130+) but we only have ~40 live Pull Requests, meaning there's a good 70-90 branches on Github that we probably don't need any more.

So, this command checks what branches exist on github that don't have a PR attached to them:

gh api repos/:owner/:repo/branches --paginate --jq '.[].name' | while read branch; do
  if [ "$branch" != "main" ] && [ "$branch" != "master" ]; then
    pr_count=$(gh pr list --head "$branch" --state all --json number --jq 'length')
    if [ "$pr_count" -eq 0 ]; then
      echo "$branch"
    fi
  fi
done

Then this version of the command changes the echo to a delete command to actually delete them:

gh api repos/:owner/:repo/branches --paginate --jq '.[].name' | while read branch; do
  if [ "$branch" != "main" ] && [ "$branch" != "master" ]; then
    pr_count=$(gh pr list --head "$branch" --state all --json number --jq 'length')
    if [ "$pr_count" -eq 0 ]; then
      git push origin --delete "$branch"
    fi
  fi
done

What this does:

1. Lists all branches on the remote
2. Skips main/master
3. Checks if any PR (open, closed, or merged) exists with that branch as the head
4. Deletes branches with zero associated PRs

This command is a little slow since it does an API call for every branch, but still only took a minute or so.

How to Delete Github / Origin Branches That Are Attached to Closed / Merged PRs

That last command does not take care of our old branches attached to closed PRs, though. This command will list those branches that are attached to PRs which were closed or merged:

gh api repos/:owner/:repo/branches --paginate --jq '.[].name' | while read branch; do
  if [ "$branch" != "main" ] && [ "$branch" != "master" ]; then
    open_pr_count=$(gh pr list --head "$branch" --state open --json number --jq 'length')
    if [ "$open_pr_count" -eq 0 ]; then
      echo "$branch"
    fi
  fi
done

And again, this next command changes echo to delete and actually deletes them:

gh api repos/:owner/:repo/branches --paginate --jq '.[].name' | while read branch; do
  if [ "$branch" != "main" ] && [ "$branch" != "master" ]; then
    open_pr_count=$(gh pr list --head "$branch" --state open --json number --jq 'length')
    if [ "$open_pr_count" -eq 0 ]; then
      git push origin --delete "$branch"
    fi
  fi
done

Again, this command is a little slow since it does an API call for every branch, but still only took a minute or so.

Simon Chiu has a nice rake task he posted that helps archive old database migration, and his post explains some of the reasons for doing so aside from being annoyed by scrolling.

His version pushes all files into a single archive, and I wanted a variation I could run that would organize these by year. I also didn't want to archive migrations from the current year, nor did I want this rake task to ever get run in production just in case, so here is a slight update on his rake task that takes those requirements into account:

namespace :db do
  namespace :migrate do
    desc "Archive migration files from past years into yearly subdirectories"
    task :archive do
      if Rails.env.production?
        puts "ERROR: This task should not be run in production environment."
        return
      end

      current_year = Date.current.year
      migrations_path = Rails.root.join("db/migrate")
      archives_path = Rails.root.join("db/migrate/archives")

      puts "Archiving migration files (excluding #{current_year})..."

      # Create archives directory if it doesn't exist
      FileUtils.mkdir_p(archives_path)

      # Get all migration files
      migration_files = Dir.glob(File.join(migrations_path, "*.rb"))

      archived_count = 0

      migration_files.each do |file|
        filename = File.basename(file)

        # Extract timestamp from filename (first 14 characters: YYYYMMDDHHMMSS)
        timestamp = filename[0, 14]

        # Skip if timestamp is invalid
        next unless timestamp.match?(/^\d{14}$/)

        # Extract year from timestamp
        file_year = timestamp[0, 4].to_i

        # Skip files from current year
        next if file_year >= current_year

        # Create year-specific archive directory
        year_archive_path = File.join(archives_path, file_year.to_s)
        FileUtils.mkdir_p(year_archive_path)

        # Move the file
        destination = File.join(year_archive_path, filename)
        FileUtils.mv(file, destination)

        puts "Archived #{filename} to archives/#{file_year}/"
        archived_count += 1
      end

      if archived_count > 0
        puts "Successfully archived #{archived_count} migration file(s)."
        puts "Current migration files remain in db/migrate/"
      else
        puts "No migration files to archive (all files are from #{current_year} or later)."
      end
    end
  end
end

Here is what you'll see in console upon running this:

And here is what you'll see if you run this twice in the same year:

If you're running Standard or Rubocop you'll likely need to make a change like this as well to ignore older migrations that don't pass linting:

ignore:
  # ignore old database migrations
  - "db/migrate/archives/**/*"

"Can't you just drag and drop these files manually?"

Yeah absolutely. But this way is more fun.

Very quickly, you'll find that /app/components/ fills up with dozens or hundreds of files, and they rarely organize themselves nicely.

I prefer to namespace components early on - usually in a shallow single folder structure.

Common ViewComponent Namespaces

Here are some examples of common folders I'll use. All of these will shift depending on the size of the app and what type of design system we're working on. Is it a CMS? SaaS app? eCommerce site? All of those will demand different setups.

UI Elements & Controls

• /buttons/ - Primary, secondary, icon buttons, button groups
• /forms/ or /fields/- Form controls, input groups, field wrappers
• /inputs/ - Text fields, selects, checkboxes, radio buttons. Sometimes I'll keep these in /fields/
• /tables/ - Data tables, sortable headers, pagination
• /navigation/ - Navbars, breadcrumbs, tabs, sidebar menus
• /modals/ - Dialog boxes, confirmations, overlays
• /dropdowns/ - Select menus, action menus, context menus
• /alerts/ - Success, error, warning, info notifications
• /badges/ - Status indicators, counts, labels
• /icons/ - SVG icons, icon wrappers, icon buttons

Depending on the number of these types of components, many of them also fit nicely into a /utilities/ namespace, eg Utility::AlertComponent.

Layout & Structure Components

Depending on the amount of layout components I'll start with a /layout/ folder, but for commonly used items like Cards or Sidebars I'll break out into separate folders.

• /layouts/ - Page layouts, grid systems, containers
• /cards/ - Content cards, product cards, user cards
• /panels/ - Collapsible panels, accordion sections
• /sections/ - Page sections, content blocks
• /headers/ - Page headers, section headers
• /footers/ - Page footers, section footers
• /sidebars/ - Navigation sidebars, filter sidebars
• /wrappers/ - Generic container components

Content Display Components

Most of these fit nicely into an Elements namespace, eg Elements::IconListComponent, but can get broken out as they increase in complexity.

• /lists/ - Ordered, unordered, definition lists
• /media/ - Images, videos, galleries, carousels
• /text/ - Typography, headings, paragraphs, quotes
• /avatars/ - User avatars, profile pictures
• /thumbnails/ - Image thumbnails, preview cards
• /tags/ - Content tags, category labels
• /progress/ - Progress bars, loading indicators
• /charts/ - Data visualization components

Interactive Elements Components

These sort of exist in between Layout and Utility and Elements namespaces and might deserve their own folders.

• /tabs/ - Tab navigation, tab content
• /accordions/ - Expandable content sections
• /toggles/ - Switch toggles, show/hide controls
• /tooltips/ - Hover tooltips, help text
• /popovers/ - Click-triggered content overlays
• /pagination/ - Page navigation, item counters
• /search/ - Search bars, filters, results
• /sorting/ - Sort controls, order toggles

Application-Specific Components

I reserve these for design patterns that really don't apply outside of the model/product area that we're working on.

• /dashboard/ - Dashboard widgets, metrics cards
• /admin/ - Admin-specific components
• /auth/ - Login forms, registration, password reset
• /profile/ - User profile components
• /settings/ - Configuration forms, preference toggles
• /comments/ - Comment threads, reply forms
• /notifications/ - System notifications, alerts
• /messages/ - Chat bubbles, message threads

Utility & System Components

These all fit well into a Utility namespace as well for simpler sites.

• /loading/ - Spinners, skeleton screens, placeholders
• /empty/ - Empty state messages, call-to-actions
• /errors/ - Error messages, 404 pages
• /confirmations/ - Confirmation dialogs, delete warnings
• /skeletons/ - Loading placeholders for content
• /overlays/ - Background overlays, dimming layers

Lookbook Organization

Similar to our ViewComponents, I like to use namespaces in Lookbook previews as well.

Lookbook will automatically handle namespaced folders for objects like class Sidebars::SidebarContainerComponentPreview < ViewComponent::Preview

You can see this on the Lookbook homepage preview image:

We were on Rails 6.0.0_rc1 while Rails was working on development for Rails 8.

We were on Ruby 2.5 shortly after 3.3 had been released.

And to top it off, we had over 90 gems in our Gemfile that were pinned haphazardly without clear logic or notes.

Getting everything up to date was a team effort, but one of the problems that needed to be solved was that we needed to do incremental updates on nearly every single dependency, upgrading them one by one and dealing with breaking changes and lack of test coverage on most of them.

When you're at the starting line and have to handle dozens or hundreds of dependency upgrades, out-of-the-box tools like bundle outdated aren't always sufficient for understanding the current state of your gemfile.

So, I began the process of writing a custom script that I could run to gather more data via the Ruby Gems API.

What My Script Does Differently

Instead of just showing me what's outdated, my script pulls together the context that actually matters:

• Release dates - I can see I'm running a gem from May 2020 versus March 2025, which tells me way more than just version numbers
• Number of versions available - 55 available versions might sound scary, but if AWS pumps out updates weekly, that's different than a gem that hasn't been touched in years
• Explicit vs implicit requirements - I only care about gems I explicitly added to my Gemfile, not the dozens of downstream dependencies that will update automatically
• Metadata - Direct links to changelogs and homepages so I can quickly assess what's changed
• Formatting - One other aspect of bundle outdated - when you copy/paste it out of the terminal it doesn't parse well into a spreadsheet. So instead of outputting a fancy format version, we just output everything to pipe|separated|data.
• Move Terminal Output to Google Sheets - Copies everything to user clipboard then opens up a new Google Sheet to set up a pivot table for analysis.

The script outputs everything, copies it to my clipboard, and automatically opens a new Google Sheet.

From there, I split the data into columns and build a pivot table that lets me filter and sort however I need.

My Outdated Gems Script

Here is the latest version which lives at bin/lib/outdated_gems_audit.rb in my app:

# From the app root folder, run the script with this command:
# >    ruby bin/lib/outdated_gems_audit.rb
# Then the script will copy the output to your clipboard and open a new spreadsheet.
# Paste into the spreadsheet and split Text To Columns by | to analyze the results.
# Add alias outdatedgems="ruby lib/scripts/outdated_gems_audit.rb" to ~/.bashrc or ~/.zshrc

require "bundler"
require "net/http"
require "json"
require "uri"
require "launchy"
require "date"

# Determine the OS to allow copy to clipboard to work
def os
  @os ||= (
    host_os = RUBY_PLATFORM.downcase
    case host_os
    when /linux/
      "linux"
    when /darwin/
      "mac"
    when /mswin|mingw|cygwin/
      "windows"
    else
      raise "unknown os: #{host_os.inspect}"
    end
  )
end

# Copy the output to the clipboard
def copy_to_clipboard(text)
  case os
  when "mac"
    IO.popen('pbcopy', 'w') { |f| f << text }
    puts "Output copied to clipboard!"
  when "linux"
    # Attempt to use xclip, but fall back to xsel if xclip is not available
    if system("command -v xclip > /dev/null")
      IO.popen('xclip -selection clipboard', 'w') { |f| f << text }
    elsif system("command -v xsel > /dev/null")
      IO.popen('xsel --clipboard --input', 'w') { |f| f << text }
    else
      raise "Clipboard utilities xclip or xsel are not installed."
    end
    puts "Output copied to clipboard!"
  when "windows"
    IO.popen('clip', 'w') { |f| f << text }
    puts "Output copied to clipboard!"
  else
    raise "Clipboard not supported on this OS"
  end
end


# Parse the Gemfile and Gemfile.lock
definition = Bundler.definition
lockfile = Bundler::LockfileParser.new(Bundler.read_file(Bundler.default_lockfile))

def fetch_url_content(url)
  uri = URI.parse(url)
  response = Net::HTTP.get_response(uri)

  case response
  when Net::HTTPSuccess then
    JSON.parse(response.body)
  else
    raise "Could not fetch URL: #{url} - Error: #{response.message}"
  end
rescue URI::InvalidURIError
  raise "Invalid URL: #{url}"
end

def fetch_gem_release_date_and_versions(gem_name, current_version)
  versions_url = "https://rubygems.org/api/v1/versions/#{gem_name}.json"
  versions_data = fetch_url_content(versions_url)

  # Extract all version numbers from the fetched data
  all_versions = versions_data.map { |v| v["number"] }
  
  # Check if a version is a prerelease (contains alpha, beta, rc, pre patterns)
  def prerelease_version?(version)
    version.match?(/\.(alpha|beta|rc|pre|dev)/i) || version.match?(/-(alpha|beta|rc|pre|dev)/i)
  end
  
  # Separate stable and prerelease versions
  versions = all_versions.reject { |v| prerelease_version?(v) }
  prerelease_versions = all_versions.select { |v| prerelease_version?(v) }

  # Calculate the number of versions newer than the current version
  current_version_index = versions.find_index(current_version)

  # Find the release date of the current version, if it exists
  current_version_data = versions_data.find { |data| data["number"] == current_version }

  # Initialize defaults
  release_date = "Not Found"
  changelog_url = ""
  homepage_url = ""

  if current_version_data
      if current_version_data["built_at"]
        # Parse the date and format it as YYYY-MM-DD
        release_date = Date.parse(current_version_data["built_at"]).strftime("%Y-%m-%d")
      end

      # Extract metadata for changelog and homepage URLs if available
      if current_version_data["metadata"]
        changelog_url = current_version_data["metadata"]["changelog_uri"] || ""
        homepage_url = current_version_data["metadata"]["homepage_uri"] || ""
      end
    end

    # Generate versions string excluding the current version (only newer versions)
    versions_available_array = current_version_index.nil? ? [] : versions[0...current_version_index]
    versions_string = versions_available_array.join(",")
    
    # Generate prerelease versions string (only newer prerelease versions)
    current_prerelease_index = prerelease_versions.find_index(current_version)
    if current_prerelease_index.nil?
      # Current version is not a prerelease, so include all newer prerelease versions
      prerelease_available_array = prerelease_versions
    else
      # Current version is a prerelease, exclude it from the list
      prerelease_available_array = prerelease_versions[0...current_prerelease_index]
    end
    prerelease_string = prerelease_available_array.join(",")

    # If current_version_index is nil, it means the current version was not found in the list
    # which should ideally not happen but could indicate an issue with version naming or data retrieval
    if current_version_index.nil?
      versions_available = "Nil"
    else
      # Versions newer than the current version
      versions_available = versions_available_array.length
    end

    [release_date, versions_available, changelog_url, homepage_url, versions_string, prerelease_string]
rescue => e
    puts "Error fetching data for #{gem_name} #{current_version}: #{e}"
    ["Release date not found", 0, "", "", "", ""]
end

def open_new_google_sheet
  Launchy.open("http://sheets.new")
rescue => e
  puts "Failed to open browser: #{e}"
end

# Store all output so we can copy it to the clipboard
headers = "Gem|Explicitly Required|Pinned At|Groups|Current|Release Date|Versions Available|Changelog URL|Homepage|Versions|Prerelease Versions"
output = "#{headers}\n"
puts headers

lockfile.specs.each do |spec|
  # Determine if the gem is explicitly required in the Gemfile
  explicitly_required = definition.dependencies.any? { |dep| dep.name == spec.name }

  # Find the version requirement and groups for the gem from the Gemfile
  dep = definition.dependencies.find { |d| d.name == spec.name }
  pinned_version = dep && dep.requirement.to_s
  groups = dep ? dep.groups.join(", ") : "default"

  # Fetch additional gem version information
  release_date, versions_available, changelog_url, homepage_url, versions_string, prerelease_string = fetch_gem_release_date_and_versions(spec.name, spec.version.to_s)

  line = "#{spec.name}|#{explicitly_required}|#{pinned_version}|#{groups}|#{spec.version}|#{release_date}|#{versions_available}|#{changelog_url}|#{homepage_url}|#{versions_string}|#{prerelease_string}"

  output += "#{line}\n"
  puts line
end

# Copy the generated output to the clipboard
copy_to_clipboard(output)

# Open a new Google Sheet for pasting the data
open_new_google_sheet

Walkthrough Video

Here's a walkthrough video on how I use the script to quickly triage all of the outdated gem dependencies in a Rails app, and how I handle ongoing maintenance updates every month or every few months. (Note: I ran this with an old branch to have more sample data, so this is not an accurate reflection of the gems currently used on that project 😄)

My Actual Gem Update Workflow

Here's how I use this in practice:

1. Run the script: ruby bin/lib/outdated_gems_audit.rb
2. Paste into Google Sheets and set up pivot table
3. Filter to only explicitly required gems
4. Sort by release date to find my oldest dependencies
5. Color code based on priority:

The actual pivot table ends up looking like this:

I typically tackle dev/test gems first since they're lower risk, then work through production dependencies.

Each gem gets its own commit in a single "gem updates" PR so I have clean CI logs if something breaks.

On larger updates that require code changes I will break off a standalone PR.

I prefix my Dependency PRs with the ⬆️ up arrow emoji to make them easier to glance through in Github history:

The biggest win is being able to prioritize more quickly and see which gems might require more review work. That context makes all the difference when you're trying to methodically work through a dependency backlog without breaking your app (or an app that's new to you).

Another perk is accumulating some historical artifacts after you complete this process a number of times. I can reference back on update history here (though it's stored in GitHub history as well)

If you're dealing with a large list of outdated dependencies, you might want to build something similar. The script is straightforward - it's just hitting the RubyGems API and formatting the response in a way that's actually useful for decision-making.

Acknowledgements: Many thanks to Jeremy Smith for pushing me to improve on my original quickly scripted version that just scraped the Ruby Gems website and instead dive into the Ruby Gems API and build a proper integration.

Sometimes these are basic app pages, like /contact/ or /support/, in which case it's easy enough to make a PagesController, route each static page to a view file like contact.html.erb, and move on with your day.

But oftentimes these are more than basic pages. These could be a collection of help docs at /docs/. Or if we're serving the public website from our main Rails app, it might include /blog/, /case-studies/, /resources/, /integrations/, /partners/, and dozens of other content collections.

In the case of these collections, the most common practice is to start out creating a standard blog implementation, and then copy and pasting that build structure each time you need a new content collection.

But, that leads to tons of code duplication, and now each time we make an upgrade related to those content types, we have to extrapolate it over every model. And when the marketing or content team wants a new content directory, it's cumbersome to launch and requires database migrations and probably some refactoring.

Need to add a featured_image? You have to add it to every model.

Need a new field so you can set custom OpenGraph metadata? Add it to every model.

These are not the hardest problems to solve. You can share partials or build components, you can copy/paste code to a few places, but eventually it will probably lead to differences in how each of the models are handled and make it harder to manage.

I use what I think is a better approach: one shared posts model and many routed content collections:

Creating A Shared Posts Model & Serving It Across Many Content Collections

There is another pattern used by CMSs like WordPress and Ghost that I prefer however, and I'm going to walk through how I've built this in Rails.

Everything is a Post

Every Post has a post_type, which might default to something like blog.

Posts also typically have a few other key columns, with an initial migration that looks like this:

create_table :posts do |t|
      t.string :title
      t.string :slug
      t.enum :status, null: false, enum_type: "post_status"
      t.json :content # assuming we're storing JSON content, depends on editor
      t.text :excerpt
      t.string :meta_title
      t.text :meta_description
      t.datetime :published_at
      t.integer :word_count
      t.string :post_type

      t.timestamps
    end

This is a simple starting point. Depending on our site requirements, at any time we want to simplify our posts model, we can always break some of these columns off to separate tables. For example:

• We could move our meta_tag values to post_metadata,
• We can store data specific to a single post_type in custom_fields, etc.
• If we use ActionText we'd skip t.json :content and use has_rich_text :content in our model instead.
• If we want to store content with revisions, we might set this up as a has_many on a post_content model instead, along with some logic for tracking the latest version. I can't find the original post, but I'm pretty sure this is roughly the model used by Basecamp when a user makes edits to an existing message or post

We don't publicly display anything as /posts/

While all of our content is stored as Posts, the Post model is entirely restricted to authorized users across Index, Show, Edit, etc.

This makes the routing simple, and the index at /posts/ effectively becomes the dashboard for our CMS. That will typically look like this in our Routes:

# Admin-only Post editing routes
  authenticated :user, ->(user) { user.admin? } do
    resources :posts
  end

Posts can be displayed through any routed Collection we want

What makes this all work is that Posts can be displayed through as many public content collections as we want.

This is similar to patterns like Custom Post Types for WordPress which store in wp_posts table, or Collections in Webflow. But I'm borrowing most heavily from Ghost, where collections are just Posts which are routed through a tagging system rather than a post_type column.

We do this by registering a controller, routes, and 2 view files. For example:

Routes Example

# Public Blog and Case Study routes (read-only)

resources :blog, controller: 'blog', path: 'blog', param: :slug, only: %i[index show]

resources :case_studies, controller: 'case_studies', path: 'case-studies', param: :slug, only: %i[index show]

Controller Example

class BlogController < ApplicationController
  def index
    @posts = filtered_posts.published
  end

  private

  def post_type
    'blog'
  end

  def filtered_posts
    Post.where(post_type: 'blog').where(status: 'published).where(indexable: true)
  end
end

I've replicated filtered_posts here without pretty scope names in order to get a glimpse of what it's doing. In reality, we'd be setting up scopes in the Post model to make it simpler to call these:

scope :published, -> { where(status: 'published') }
scope :indexable, -> { where(indexable: true) }
scope :blog_posts, -> { where(post_type: 'blog') }
scope :case_studies, -> { where(post_type: 'case_study') }

View Files - Index & Show

Finally, we have 2 core view files for index and show.

For this example each page serves up basic page metadata and then passes all posts into Posts::IndexComponent or Posts::ShowComponent ViewComponents, which handle the actual formatting of posts.

<%= page_title("Blog") %>
<%= meta_tag :title, "Blog" %>
<%= meta_tag :description, "Here is my blog index meta description" %>
<%= meta_tag :url, blog_index_url %>
<%= canonical_url(blog_index_url) %>

<%= render Posts::IndexComponent.new(
  posts: @posts, 
  admin_links: current_user&.admin?,
  title: "Blog",
  new_post_url: new_post_path(post_type: "blog"),
  post_type: "blog"
) %>

<%= page_title(@post.meta_title.presence || @post.title) %>
<%= meta_tag :title, @post.meta_title.presence || @post.title %>
<%= meta_tag :description, @post.meta_description.presence || @post.excerpt.presence || "Read #{@post.title} on the Site Name blog." %>
<%= meta_tag :url, blog_url(@post.slug) %>
<%= canonical_url(blog_url(@post.slug)) %>
<% if @post.featured_image.attached? %>
  <%= meta_tag :image, url_for(@post.featured_image) %>
  <%= meta_tag :image_alt, @post.title %>
<% end %>

<%= render Posts::ShowComponent.new(
  post: @post,
  admin_links: current_user&.admin?,
  back_url: blog_index_path,
  back_label: "← Back to blog"
) %>

Benefits

Centralized Feature Development

This is the big one.

When you need to add a new feature like featured images, OpenGraph metadata, or reading time estimates, you add it once to the Posts model and immediately every content collection gets it. No more copying the same migration across Blog, CaseStudy, HelpDoc, and Resource models. No more forgetting to update one collection and having inconsistent functionality across your site.

Need to do a fancy callback to calculate word_count after the post is updated? Just do it once.

Need to generate url slug if blank upon creation but then validate it each time the user saves? Just do it once.

Need to do special handling for ActiveStorage attachments on Trix that are intended to be published publicly and need to serve cleaner URLs? Just do it once.

Consistent SEO & Metadata Management

Every post gets the same meta_title, meta_description, and SEO handling regardless of whether it's a blog post or a case study.

Your sitemap generation becomes trivial—just iterate individually through each collection of posts.

Structured data markup can be standardized with a single component that adapts based on post_type. You'll never have that awkward moment where your blog has perfect SEO but your case studies are missing Open Graph tags.

Simplified Content Administration

Your CMS interface becomes incredibly clean. Instead of having separate admin sections for blog posts, case studies, help docs, and resources, you have one unified posts dashboard. You can filter by post_type, but all the core functionality—editing, publishing, scheduling—works the same way everywhere. Your content team learns one interface instead of four.

Here's an example I built recently for Posts#index that includes param filters on top of the page. These were part of a quick spike that took 3 hours for the entire Posts + collections build out, so design isn't perfected, but it looks way better than your average internal admin screen in regards to editing content:

And here's the Post#edit view:

Reduced Code Duplication

Personally I think this is one area where this pattern shines. If I didn't do this approach, I would be racking my brain trying to figure out the best way to break up a lot of this stuff into concerns.

But overall this approach should cut down on a lot of find/replace type of commits.

Add New Content Collection in 15 Minutes With No Migrations

Need to add a new content collection like /testimonials/ or /press-releases/? It's literally just creating a new controller that inherits from PostsController, adding a route, and copy/pasting two view files to build off of an existing page template.

You can spin up a new content type in 15 minutes instead of spending a day building out new models, refactoring controller and model concerns, updating your admin config to match existing content models, etc.

Easy Search and Filtering

Want to add site-wide search?

You're searching one table instead of trying to union across multiple models.

Want to show "related content" that might pull from different collections?

Easy—just query posts with different post_types.

Need to show recent activity across all content types in your admin dashboard?

☝️ One query.

Common Concerns

Here are some common variations or concerns that show up and how I'd solve them:

What if I want to display the content differently on each post_type?

This is a common one! What if we don't want to display author name on one of the posts types? What if we want to show table of contents on one post_type but not all?

Most of the time, this is easily solved by just altering the index or show view templates. Those views can share as much or as little styling as we want, so it's easy to create different layouts by post_type.

It's also very easy to create different page layouts, eg a layout column which is set to default but can be changed to full_width vs slim.

What if I need to store different data types for a post_type?

There are a lot of patterns to solve this and it opens up discussions about delegated types and other stuff that honestly, I'm not the most qualified Rails developer to weigh in on.

However the pattern that I would reach that is similar to WordPress is simply to create a pattern like has_many custom_fields, or perhaps a tag system. Then my custom_fields table would simply store a key value pattern for custom_fields, or for simpler labels I would use a tag.

You want case studies to have an industry category that allows you to filter sub-collections on the case studies index page?

Add a new tag, then add special routes for those tags or serve them up via url param, eg /case-studies/?industry=saas.

You want case studies to store customer quotes that can be displayed dynamically in your case_study#show template?

Add a custom_field.

You want to store and entire section of custom HTML for a page that displays above the regular Post.content section?

Same deal - format it with a special partial or ViewComponent, and put the dynamic stuff in a custom_field.

We could get into a lot of theoretical discussions about whether this is over-using a custom_field relationship and whether it makes it hard to validate and monitor the data being stored in custom_field, but how strict you are with that stuff is really up to you. If this is to support a few hundred pages of content on one app then all of this stuff will scale just fine.

What about URL structure and SEO implications?

This is one of the best benefits in my opinion.

All of your URLs need to have custom slugs, which this system handles well. If you want to validate uniqueness by post_type so that you have have /blog/special-slug and /case-studies/special-slug you can do that just fine. The routing handles the collection-specific paths while the underlying data structure remains unified.

For our other settings, you get consistent metadata handling, easier sitemap generation, and unified canonicalization logic. The main thing to watch out for is if you ever need to change a post's post_type—you'll want to set up proper redirects from the old URL to the new collection.

How do you handle different editorial workflows?

Not every content type needs the same publishing workflow. Your blog posts might go straight to published, but case studies might need approval from a sales manager first.

IMO that's usually better managed outside of your app in most small to mid-sized organizations. If you can manage a single repeatable content approval process across all content types, then you should be able to build that into this model the same as you would if all of the Posts were separate models.

What about site performance with large datasets?

Once you're dealing with thousands of posts across multiple types, you might want to optimize this structure a little. I haven't reached this point on Rails but I definitely have on some of the WordPress publishing sites I manage.

Claude suggests:

• think about indexing, such as composite indexes on (post_type, status, published_at) and (post_type, slug) since those are your most common query patterns.
• for really large datasets, you might consider moving to separate models and using concerns instead.
• implement some basic caching—eg fragment caching for your index pages and Russian doll caching for individual posts.

How do you manage different content schemas?

Different post types often need different structured data markup. Blog posts need Article schema, case studies might need Service schema, and help docs might need HowTo schema.

I would handle this by adding schema logic to my ShowComponent that switches based on post_type. Most of the Schema is going to be generated off of Post Title, meta description, featured image, etc. Anything else can be pulled from custom fields.

How do security and permissions work across post types?

That's up to you - I always just piggyback whatever methods we have already implemented with Devise, CanCanCan, etc to check for (A) whether user is logged in and (B) whether they have admin privileges. In a more complex environment I would probably add a set of author privileges that is similar to admin but allows post editing access instead of admin privileges.

What happens when you need drastically different data models?

There's definitely a breaking point where the custom_fields approach becomes unwieldy. If one of your post types needs 15 custom fields with complex validation rules, or if you need heavy relational data that doesn't fit the key-value pattern, it might be time to extract that post_type to its own model.

The nice thing is that you can do this gradually. Keep the unified model for most content types and extract the complex ones as needed. You're not locked into the pattern forever.

This is a pretty straightforward feature, but delivers a nicer branded experience when you need to put a Heroku app into maintenance mode. We recently did this on Content Harmony both for Postgres upgrades, as well as while migrating our database to a new provider.

If you read the docs, you can set any URL as the page that is shown during maintenance mode, rather than this Heroku branded page.

So, we created a dedicated page on our marketing site (which runs on Ghost, not Rails and Heroku, so isn't affected by maintenance mode).

The page lives at /maintenance-mode, and we also added <meta name="robots" content="noindex"> to make it clear that the page should not be indexed by Google, etc.

From there, you just list that URL as a Config Var for MAINTENANCE_PAGE_URL in your Heroku settings for your app:

The page will now appear any time you run or toggle the Maintenance Mode in your App's settings:

On a recent client project we were generating a single sitemap for a variety of content types, including static pages, blog posts, and 2-3 custom content directories.

You can imagine a basic config/sitemap.rb setup like this from the sitemap_generator Readme:

SitemapGenerator::Sitemap.default_host = 'http://example.com'

SitemapGenerator::Sitemap.create do
  add '/about', :changefreq => 'daily', :priority => 0.9
  add '/contact_us', :changefreq => 'weekly'

  Article.published.each do |article|
    add article_path(article), priority: 0.64, changefreq: 'weekly'
  end
end

SitemapGenerator::Sitemap.ping_search_engines # Not needed if you use the rake tasks

I want to walk through a few changes I made to improve this sitemap and why.

Break Into Sitemap Index + Multiple Sitemaps

I prefer to generate multiple individual sitemaps for different content directories.

That's because when you submit those sitemaps to Google Search Console, it's much easier to analyze URL performance by content type:

Now, after submitting each of those sitemaps into Search Console, I can get more granular breakdowns of which content is being indexed and which isn't, which helps me make decisions around internal linking, identify why pages aren't ranking, etc.

Break Sitemap into separate files using group(filename: xyz)

Sitemap_generator has a nice built-in group feature to handle this:

# Set the root domain
SitemapGenerator::Sitemap.default_host = "https://www.example.com"

SitemapGenerator::Sitemap.create do
  group(filename: :sitemap_pages) do
    add '/about', :changefreq => 'daily', :priority => 0.9
    add '/contact_us', :changefreq => 'weekly'
  end
  
  group(filename: :sitemap_articles) do
    Article.published.each do |article|
      add article_path(article), priority: 0.64, changefreq: 'weekly'
    end
  end
end

Add to root back to the pages group using into separate files using include_root: true

When you use the group feature, sitemap_generator stops adding your homepage to a sitemap. You can add it back using include_root: true in the pages group we established above:

group(filename: :pages, include_root: true) do
    add '/about', :changefreq => 'daily', :priority => 0.9
    add '/contact_us', :changefreq => 'weekly'
  end

Set create_index = true to generate a sitemap_index file

Our next step is to tell sitemap_generator to build a sitemap_index file. A sitemap_index file is simply an index of all of your grouped sitemaps.

It is a nice feature because we can add a single sitemap reference to robots.txt and bots will find all of the sitemaps we might generate in the future:

# robots.txt

Sitemap: https://www.example.com/sitemaps/sitemap_index.xml.gz

No matter how many new groups we add to our config/sitemap.rb, they'll automatically be referenced by this robots.txt entry. For big sites that is huge because it will automatically include sitemaps that get paginated or broken up after exceeding the maximum URL count per sitemap file.

We can generate that using the following before our create command:

# Create a sitemap index which points to all sitemap files
SitemapGenerator::Sitemap.create_index = true

Many CMSs or SEO plugins will name this file sitemap_index.xml by default. Sitemap_generator doesn't do that, it just names the file sitemap.xml, so if we'd like, we can override the index filename in the create command to make the filename more explicit.

# Set the root domain
SitemapGenerator::Sitemap.default_host = "https://www.example.com"

# Create a sitemap index which points to all sitemap files
SitemapGenerator::Sitemap.create_index = true

SitemapGenerator::Sitemap.create(filename: 'sitemap_index') do
  group(filename: :sitemap_pages, include_root: true) do
    add '/about', :changefreq => 'daily', :priority => 0.9
    add '/contact_us', :changefreq => 'weekly'
  end
  
  group(filename: :sitemap_articles) do
    Article.published.each do |article|
      add article_path(article), priority: 0.64, changefreq: 'weekly'
    end
  end
end

Generate both .xml and .xml.gz sitemap versions

By default, sitemap_generator will generate compressed sitemaps, meaning a gzipped .xml.gz file.

Those are smaller in filesize and better for serving to bots as well as for submitting to Google Search Console.

But - they don't render in the browser, they download when you load them. And I don't know about you, but Microsoft Word is really excited to be the default app on my Mac when I unzip them and try to load the .xml file locally.

So instead, it's nice to generate an uncompressed .xml file as well which can be viewed in the browser. This makes it much easier for developers to load the .xml version in local, staging, and production to see which how URLs are being loaded in each sitemap file.

Thankfully, we can do this pretty easily by calling the :compress option, and running SitemapGenerator::Sitemap.create twice:

# Set the root domain
SitemapGenerator::Sitemap.default_host = "https://www.example.com"

# Create a sitemap index which points to all sitemap files
SitemapGenerator::Sitemap.create_index = true

# Generate both compressed and uncompressed versions
[true, false].each do |compress_value|
  SitemapGenerator::Sitemap.compress = compress_value

  SitemapGenerator::Sitemap.create(filename: 'sitemap_index') do
    group(filename: :sitemap_pages, include_root: true) do
      add '/about', :changefreq => 'daily', :priority => 0.9
      add '/contact_us', :changefreq => 'weekly'
    end
    
    group(filename: :sitemap_articles) do
      Article.published.each do |article|
        add article_path(article), priority: 0.64, changefreq: 'weekly'
      end
    end
  end
end

In this example we're iterating through the [true, false].each do |compress_value| array, using it to set SitemapGenerator::Sitemap.compress = compress_value before running .create, which ends up generating .xml and .xml.gz copies of every sitemap file.

Here's an example of what our output looks like for a site with 4 groups, a sitemap index, and both .xml and .xml.gz output:

In '/Users/kanejamison/Github/ltbweb/public/':
+ sitemap_pages.xml.gz                   26 links / 591 Bytes
+ sitemap_blog.xml.gz                    22 links / 911 Bytes
+ sitemap_resources.xml.gz             2713 links /   40.2 KB
+ sitemap_services.xml.gz                19 links / 453 Bytes
+ sitemap_sitemap_index.xml.gz         4 sitemaps / 263 Bytes

Sitemap stats: 2,780 links / 4 sitemaps / 0m00s

In '/Users/kanejamison/Github/ltbweb/public/':
+ sitemap_pages.xml                      26 links /   4.71 KB
+ sitemap_blog.xml                       22 links /   5.14 KB
+ sitemap_resources.xml                2713 links /    510 KB
+ sitemap_services.xml                   19 links /   3.97 KB
+ sitemap_sitemap_index.xml            4 sitemaps / 776 Bytes

Sitemap stats: 2,780 links / 4 sitemaps / 0m00s

Take note at the filesize difference on the gzipped versions. It's certainly nice to point bots to those versions, especially with how much AI bot activity is happening nowadays.

If you're on Heroku, you're not done.

This part gets a little confusing.

If you're on a host that allows you to build static xml files dynamically on the server, you might be good to go. You'll need to set up a cron job for rake sitemap:refresh, after which, you'll have a fresh sitemap however often you like.

But if you're on Heroku, you can't build static assets on the server and keep them there. If I understand correctly they'll let you build the files in /tmp/, but you can't just drop them in /public/, you'll need to set up a storage adapter, which is heavily documented on sitemap_generator's docs.

Sometimes it is desirable to host your sitemap files on a remote server, and point robots and search engines to the remote files. For example, if you are using a host like Heroku, which doesn't allow writing to the local filesystem. You still require some write access, because the sitemap files need to be written out before uploading. So generally a host will give you write access to a temporary directory. On Heroku this is tmp/ within your application directory.

When you switch to using a storage adapter, then a lot of our setup above becomes a problem.

As sitemap_generator explains in their section on storage adapters:

Note that SitemapGenerator will automatically turn off include_index in this case because the sitemaps_host does not match the default_host. The link to the sitemap index file that would otherwise be included would point to a different host than the rest of the links in the sitemap, something that the sitemap rules forbid.

So, that's a problem - if we can't store our sitemap on the server, and we can't generate a sitemap index, then we're left with a couple of options.

One is that we can hardcode our sitemap file references in robots.txt. On a smaller site that might be feasible, but if we're creating multiple sitemaps of a certain type, eg sitemap_posts.xml, sitemap_posts2.xml, then it would require us to manually keep track of how many sitemaps are getting created and update that robots.txt entry manually.

[post in progress until this note is gone, still finishing this end section]

STILL TO COVER:

• REVERSE PROXY / NGINX to serve files from our domain URLs.
• Or, whether redirects will work.
• Whether we can override the sitemap_index disabled feature if we're willing to handle the URL controls in one of those ways.

After copy and pasting expect(page).to have_css "meta[name='robots'][content='noindex']", visible: :hidden for the 5th time it was clear I needed to build out some helper commands that were simpler and more clear.

I came up with the following SEO Helper that lives at spec/support/seo_helper.rb.

These tests are primary checking for meta tags. So if you want to verify other requirements like presence in sitemaps that isn't currently covered by this helper.

If you use this in your own app, you'll need to possibly modify values. For instance when we set meta robots to noindex, if you only set a value of noindex as opposed to noindex, follow, you might need to change that value.

# spec/support/seo_helper.rb

module SEOHelper
  # Check if the page has indexable meta robots tag
  def expect_that_page_is_indexable
    expect(page).to have_css "meta[name='robots'][content='index, follow']", visible: :hidden
  end

  # Check if the page has non-indexable meta robots tag
  def expect_that_page_is_noindexed
    expect(page).to have_css "meta[name='robots'][content='noindex, follow']", visible: :hidden
  end

  # Check that canonical URL path exactly matches the expected path
  # Include the full path after domain
  # eg expect_canonical_url_path_matches("/about-us")
  def expect_canonical_url_path_matches(expected_path)
    # Get the actual canonical URL from the page
    canonical_element = find("link[rel='canonical']", visible: :hidden)
    actual_url = canonical_element[:href]

    # Parse the URL to get just the path
    actual_uri = URI.parse(actual_url)
    actual_path = actual_uri.path

    # Ensure expected_path starts with a slash
    expected_path = "/#{expected_path}" unless expected_path.start_with?('/')

    # Check if the path exactly matches the expected path
    expect(actual_path).to eq(expected_path),
                           "Expected canonical path to be '#{expected_path}', but got '#{actual_path}'"
  end

  # Check for specific meta description
  def expect_meta_description(expected_content = nil)
    if expected_content
      expect(page).to have_css "meta[name='description'][content='#{expected_content}']", visible: :hidden
    else
      expect(page).to have_css "meta[name='description']", visible: :hidden
    end
  end

  # Check for exact page title
  def expect_page_title_matches(expected_title)
    expect(page).to have_title expected_title
  end

  # Check that page title contains the expected text
  def expect_page_title_contains(expected_text)
    expect(page.title).to include(expected_text),
                          "Expected page title to contain '#{expected_text}', but got '#{page.title}'"
  end
end

RSpec.configure do |config|
  config.include SEOHelper
end

Here's an example of how we use this:

require 'rails_helper'

# Note - most tests in this file are confirming that landing pages on the website are renderable, indexable, and that the canonical tag is generated as expected.
# If you need to test specific functionality on these pages it probably deserves a separate spec.
# Pages are sorted alphabetical by URL.

RSpec.describe 'Visit Core Pages', type: :feature do
  it "renders the home page as expected" do
    visit "/"
    expect(page).to have_text("Here is a paragraph that would only appear on the Home page and definitely not in our footer or other pages of the site that would cause false positives.")
    expect_that_page_is_indexable
    expect_canonical_url_path_matches("/")
  end

  it "renders the /about-us page as expected" do
    visit "/about-us"
    expect(page).to have_text("Here is a paragraph that would only appear on the About Us page and definitely not in our footer or other pages of the site that would cause false positives.")
    expect_that_page_is_indexable
    expect_canonical_url_path_matches("/about-us")
  end

   # etc for other critical pages

end

I don't need to check the following types of values currently, but here are some likely ways to expand this helper in the future:

1. Testing for Open Graph meta tags (eg og:url matches canonical tag)
2. Verifying redirect paths are 301 and "single hop"
3. Verifying JSON-LD structured data presence and validity
4. Checking hreflang tags for multilingual sites
5. Validating meta viewport settings
6. Testing for proper heading hierarchy (H1, H2, etc.)
7. Checking for rel="next" and rel="prev" pagination tags
8. Verifying image alt attributes on critical images
9. Checking for sitemap.xml references in robots.txt
10. Validating proper URL trailing slash consistency (this is partially inherent in our canonical path checker, however you might need to also render the page with a trailing slash and confirmed canonical does not include it)
11. Checking for rel="nofollow" on specific links
12. Testing breadcrumb markup
13. Verifying schema.org markup for specific page types
14. Testing for proper canonical links on taxonomy pages, paginated pages, pages with parameters, etc.
15. Checking for proper sitemap formatting
16. Testing for valid RSS feeds