Add parent relationship to deprecations to allow grouping in the UI,

especially in the index

- Added `since` to the metadata display since I felt it was missing
  especially on the id route
- Made id in the metadata display link to the individual id page to
  expose those URLs
- Added some info to the README about the new relationship but also
  about adding deprecation guides

Author: kategengler

README.md

@@ -5,10 +5,27 @@
 
 This is the app that serves https://deprecations.emberjs.com/
 
+## Linking to deprecations
+
+You can link to a specific deprecation by using the ID of the deprecation. For example, to link to the deprecation with the ID `my-old-api`, you can use the following URL:
+`https://deprecations.emberjs.com/id/my-old-api`. These URLs can be generated in advance of adding the deprecation guide, when the deprecation lands in the code.
+When adding a deprecation the filename should match the ID of the deprecation, or the `displayId` should be specified in the frontmatter.
+
 ## Adding new deprecations
 
 The [content](https://github.com/ember-learn/deprecation-app/tree/main/content/) folder contains all the deprecations that are listed by the website. To add a new deprecation, add it to the appropriate folder by creating a new file. The content of the file needs to follow a specific format for the app to work. You can see [this sample](https://raw.githubusercontent.com/ember-learn/deprecation-app/main/content/ember/v3/getting-the-each-property.md) for reference.
 
+### Frontmatter
+
+#### Grouping deprecations
+
+```markdown
+  parent: deprecation-id
+```
+
+Can be used to nest deprecations under a parent grouping for the purpose of the UI. The deprecations will still be available via the direct ID URLs.
+
+
 ## Prerequisites
 
 You will need the following things properly installed on your computer.

app/components/deprecation-article.js

@@ -1,10 +1,19 @@
 import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
 export default class DeprecationArticle extends Component {
+  @tracked showChildDeprecations = false;
+
   get idForTitle() {
     return `toc_${this.args.model.title}`;
   }
 
   get idForUntil() {
     return `toc_until-${this.args.model.until}`;
   }
+
+  @action
+  toggleChildDeprecations() {
+    this.showChildDeprecations = !this.showChildDeprecations;
+  }
 }

app/models/content.js

@@ -1,4 +1,4 @@
-import Model, { attr } from '@ember-data/model';
+import Model, { attr, belongsTo, hasMany } from '@ember-data/model';
 
 export default class ContentModel extends Model {
   @attr content;
@@ -7,6 +7,8 @@ export default class ContentModel extends Model {
   @attr since;
   @attr anchor;
   @attr displayId;
+  @belongsTo('content', { inverse: 'children', async: false }) parent;
+  @hasMany('content', { inverse: 'parent', async: false }) children;
 
   // v1 has different meta, so conditionally render it
   get renderUntil() {

app/templates/components/deprecation-article.hbs

@@ -3,10 +3,30 @@
   <div class="my-2">
     {{#if @model.renderUntil}}
       <div><span class="bold">until: </span>{{@model.until}}</div>
-      <div><span class="bold">id: </span>{{or @model.displayId @model.id}}</div>
+      <div><span class="bold">since: </span>{{@model.since}}</div>
+      <div><span class="bold">id: </span><LinkTo @route="id" @model={{@model.id}}>{{or @model.displayId @model.id}}</LinkTo></div>
+    {{/if}}
+    {{#if @model.parent}}
+      <div><span class="bold">included in: </span><LinkTo @route="id" @model={{@model.parent.id}}>{{or @model.parent.displayId @model.parent.id}}</LinkTo> </div>
+    {{/if}}
+    {{#if @model.children.length}}
+      <div><span class="bold">includes: </span> {{@model.children.length}} deprecations <button type="button" {{on "click" this.toggleChildDeprecations}}>{{(if this.showChildDeprecations 'Collapse all' 'Expand all')}}</button></div>
     {{/if}}
   </div>
+  {{#if this.showChildDeprecations}}
+    {{#each @model.children as |child|}}
+      <DeprecationArticle @model={{child}}>
+        <h3>
+          {{markdown-to-html
+            child.title
+            extensions="no-wrapper"
+            tagName=""
+          }}
+        </h3>
+      </DeprecationArticle>
+    {{/each}}
+  {{/if}}
   <section>
     {{markdown-to-html @model.content}}
   </section>
-</div>
+</div>

app/utils/process-results.js

@@ -5,6 +5,9 @@ const GLIMMER = 'Glimmer Internals';
 
 export default function processResults(query) {
   let results = query.toArray().reduce((results, item) => {
+    if (item.parent) {
+      return results;
+    }
     let since = results.find((result) => result.since === item.since);
     if (!since) {
       since = { since: item.since, contents: [] };

lib/content-docs-generator/index.js

@@ -26,6 +26,7 @@ const jsonTrees = contentFolders.map(
   (type) =>
     new StaticSiteJson(`content/${type}`, {
       attributes: ['title', 'since', 'until', 'anchor', 'displayId'],
+      references: [{ name: 'parent', type: 'content' }],
       type: 'contents',
       collate: true,
       collationFileName: `${type.replace(/\//, '-')}.x.json`,