New 'Repos' page and consolidation of 'Apps' page

[ChrisBAshton]

Alongside the refactoring in #3509, there are some related visual improvements. Here is a summary of the changes:

Addition of a 'Repos' page

#3481 saw the addition of a 'repos.json' alongside the longstanding 'apps.json' functionality. So it seems only natural that we should also want a summary page of Repos alongside our summary page of Apps.

Addition of 'Repos' link in header

See above.

Changes to 'Apps' page

The addition of the 'Repos' page led to some duplication etc, which got consolidated and visually reviewed, and eventually led to the following improvements to the Apps page. It removed the need for a separate 'by team' page.

Before:

After:

Removal of the 'apps by team' page

The existing page is no longer required once these changes are merged.

Trello: https://trello.com/c/oUsgzZnk/247-standardise-how-we-represent-repositories-in-the-dev-docs

[benthorner]

Works locally for me ✅.

Great to see the emerging focus on repos vs. apps 🚀.

Do we really need the "apps" page anymore? All the info that's on it can be seen on the new "repos" page. Seeing both of them, I half expected the links on the "apps" page to go to the live app, but what we really mean by "app" is "app repository", not the running version of it. I don't feel strongly about this, though. What are your thoughts?

Looking at the code itself, do you think it's worth adding some tests for the new / updated pages? There's some precedent for it but I also get that this isn't that much of a change from what was there before. Otherwise, all my comments are just some ideas for how to polish the new layout / content a bit.

[ChrisBAshton]

Thanks for the review, @benthorner! I've addressed all the individual comments if you'd like to re-review 👀

Do we really need the "apps" page anymore? All the info that's on it can be seen on the new "repos" page.

Part of the reason to properly support the concept of 'repos' rather than just 'apps' was the confusion some teams were facing when looking at what used to be applications.yaml, and seeing non-apps in there. We wanted to include non-apps so that we could surface all relevant documentation via search, but it led to confusion with stakeholders, particularly around things like Rails upgrades. Think "we've only updated 7 apps, but I see we're responsible for 10, why haven't we done the other 3 yet?", when the other 3 are gems etc.

So for that reason, I think it's still worth having a distinct grouping of 'apps' vs 'repos'.

Seeing both of them, I half expected the links on the "apps" page to go to the live app, but what we really mean by "app" is "app repository", not the running version of it.

Yes, that's a good point. I think once this is merged we could look at making the app and app-overview pages a bit more tailored to apps. Don't think it's a blocker for this PR though.

Looking at the code itself, do you think it's worth adding some tests for the new / updated pages? There's some precedent for it but I also get that this isn't that much of a change from what was there before.

The existing tests are really just linting: redirect_spec.rb checks that redirects aren't missing their .html suffix, and manual_page_spec.rb checks that every page's frontmatter has an owner, a title, etc. I don't think we really have a precedent for testing the contents of pages.
More tests in general would probably be a good thing, but I agree that the changes in this PR aren't very different to what was there before and so doesn't introduce any new risks.

[benthorner]

Ready to 🚢.

I like the argument of keeping the page with a view to tailoring it in future. And in the meantime the mysterious "stakeholders" can still benefit from it 😜.