deprecate Primer::TimeAgoComponent in favor of `Primer::RelativeTim…

…e` (#1692)

.changeset/mean-poets-poke.md

@@ -0,0 +1,5 @@
+---
+'@primer/view-components': patch
+---
+
+Deprecating Primer::TimeAgo in favor of Primer::RelativeTime, and adding a migration guide

app/components/primer/time_ago_component.rb

@@ -3,7 +3,7 @@
 module Primer
   # Use `TimeAgo` to display a time relative to how long ago it was. This component requires JavaScript.
   class TimeAgoComponent < Primer::Component
-    status :beta
+    status :deprecated
 
     # @example Default
     #   <%= render(Primer::TimeAgoComponent.new(time: Time.at(628232400))) %>

docs/content/guides/primer_time_ago.md

@@ -0,0 +1,50 @@
+---
+title: Moving Away From `Primer::TimeAgoComponent`
+---
+
+This guide will show you how to upgrade from the now deprecated
+[`Primer::TimeAgoComponent`](https://primer.style/view-components/components/timeago)
+to the latest [`Primer::Beta::RelativeTime`](https://primer.style/view-components/components/beta/relativetime)
+component.
+
+## A Migration Example
+
+Use of the `TimeAgoComponent` component can be migrated with only a few minor changes.
+
+For example, if the `TimeAgoComponent` was set up in this way:
+
+```rb
+<%= render(Primer::TimeAgoComponent.new(time: Time.at(628232400))) %>
+```
+
+It can be migrated by renaming `time` to `datetime`, and adding the `tense:
+:past` setting.
+
+```rb
+<%= render(Primer::Beta::RelativeTime.new(datetime: Time.at(628232400), tense: :past)) %>
+```
+
+## Arguments
+
+The majority of options available in `RelativeTime` are not relevant when
+using it as a replacement for `TimeAgo`. There are a few changes that need to be
+noted, however.
+
+| From `Primer::TimeAgoComponent` | To `Primer::Beta::RelativeTime` | Notes |
+|---------------------------------|---------------------------------|-------|
+| `time`  | `datetime`       | Renamed argument, but the semantics remain the same                                                                     |
+| `micro` | `format: :micro` | Instead of a boolean flag, set the `format` argument to the value of `:micro`                                           |
+| n/a     | `tense: :past`   | Required for displaying how long ago the set time was. This argument tells `RelativeTime` to behave like `TimeAgo` did. |
+
+The remaining arguments for `RelativeTime` can be found in the docu7mentation
+for that component.
+
+Please see the following for complete descriptions and examples.
+
+* [Deprecated `Primer::TimeAgoComponent`](https://primer.style/view-components/components/timeago)
+* [`Primer::Beta::RelativeTime` component](https://primer.style/view-components/components/beta/relativetime)
+* [`Primer::Beta::RelativeTime` Lookbook examples](https://primer.style/view-components/lookbook/inspect/primer/beta/relative_time_preview/default)
+
+<p>&nbsp;</p>
+
+[&larr; Back to migration guides](https://primer.style/view-components/migration)

docs/content/migration.md

@@ -30,3 +30,4 @@ components.
 | [`Primer::ButtonComponent`](https://primer.style/view-components/components/button) | [`Primer::Beta::Button`](https://primer.style/view-components/components/beta/button) | [Upgrade to Primer::Beta::Button](https://primer.style/view-components/guides/primer_button_component) |
 | [`Primer::DropdownMenuComponent`](https://primer.style/view-components/components/dropdownmenu) | [`Primer::Alpha::Dropdown`](https://primer.style/view-components/components/alpha/dropdown) | [Upgrade to Primer::Alpha::Dropdown](https://primer.style/view-components/guides/primer_dropdown_menu_component) |
 | [`Primer::LocalTime`](https://primer.style/view-components/components/localtime) | [`Primer::Beta::RelativeTime`](https://primer.style/view-components/components/beta/relativetime) | [Upgrade to Primer::Beta::RelativeTime](https://primer.style/view-components/guides/primer_local_time) |
+| [`Primer::TimeAgoComponent`](https://primer.style/view-components/components/timeago) | [`Primer::Beta::RelativeTime`](https://primer.style/view-components/components/beta/relativetime) | [Upgrade to Primer::Beta::RelativeTime](https://primer.style/view-components/guides/primer_time_ago) |

docs/src/@primer/gatsby-theme-doctocat/nav.yml

@@ -103,8 +103,6 @@
     url: "/components/beta/text"
   - title: TextField
     url: "/components/alpha/textfield"
-  - title: TimeAgo
-    url: "/components/timeago"
   - title: TimelineItem
     url: "/components/timelineitem"
   - title: ToggleSwitch
@@ -131,6 +129,8 @@
     url: "/components/iconbutton"
   - title: LocalTime
     url: "/components/localtime"
+  - title: TimeAgo
+    url: "/components/timeago"
   - title: Tooltip
     url: "/components/tooltip"
 - title: Architecture decisions

lib/primer/deprecations.yml

@@ -80,6 +80,11 @@ deprecations:
     autocorrect: true
     replacement: "Primer::Beta::Popover"
 
+  - component: "Primer::TimeAgoComponent"
+    autocorrect: false
+    replacement: "Primer::Beta::RelativeTime"
+    guide: "https://primer.style/view-components/guides/primer_time_ago"
+
   - component: "Primer::Tooltip"
     autocorrect: true
     replacement: "Primer::Alpha::Tooltip"

lib/tasks/docs.rake

@@ -515,7 +515,7 @@ namespace :docs do
   def lookbook_url(component)
     path = component.name.underscore.gsub("_component", "")
 
-    "https://primer.style/view-components/lookbook/inspect/#{path}/default/"
+    "https://primer.style/view-components/lookbook/inspect/#{path}_preview/default/"
   end
 
   def preview_exists?(component)