Change ID to fix a broken UI link

asteflova commented 1 month ago

What changes are you introducing?

Adding a secondary ID to the assembly for registering hosts.

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Another PR recently changed the ID which broke a UI link: https://github.com/theforeman/foreman-documentation/pull/3327#discussion_r1791397965

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

N/A

Checklists

[x] I am okay with my commits getting squashed when you merge this PR.
[x] I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

[x] Foreman 3.12/Katello 4.14 (Satellite 6.16)
[ ] Foreman 3.11/Katello 4.13
[ ] Foreman 3.10/Katello 4.12
[ ] Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
[ ] Foreman 3.8/Katello 4.10
[ ] Foreman 3.7/Katello 4.9 (Satellite 6.14)
[ ] Foreman 3.6/Katello 4.8
[ ] Foreman 3.5/Katello 4.7 (Satellite 6.13; orcharhino 6.6/6.7)
We do not accept PRs for Foreman older than 3.5.

github-actions[bot] commented 1 month ago

The PR preview for cd59b1a11688c7fd10e5a038d4590c789c894fda is available at theforeman-foreman-documentation-preview-pr-3358.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

asteflova commented 1 month ago

@maximiliankolb @evgeni What would you think about this? I'm hoping this would resolve the error described in https://github.com/theforeman/foreman-documentation/pull/3327#discussion_r1791397965 (as reported by @evgeni) while also allowing us to use matching IDs and filenames within the docs set (as recommended by @maximiliankolb). Can it work? Or am I missing something?

evgeni commented 1 month ago

Doesn't look too crazy to me. :woman_shrugging:

asteflova commented 1 month ago

why not the other way around?

RH d/s guides can be displayed in html-single or multi-page format. The UI link that got broken links to the multi-page format. The links we use throughout the docs set link to the html-single format.

I have been able to confirm that the secondary IDs work with the html-single format. It looks like the multi-page format keeps relying on the primary ID.

That's why I'd like to use the "old" ID as the primary one -- that should make the UI link work again. We can define the "new" ID (which properly matches the heading and file name) as the secondary one because that one should work with all the cross links in this docs set.

I feel the need to add that although I spent a full hour fiddling with links and IDs in our d/s docs staging area, there is still a good chance that I'm wrong, in which case this PR won't fix anything and I will need to revert back to using the "old" ID everywhere. I still think this is worth a try. Does this make sense @maximiliankolb?

maximiliankolb commented 1 month ago

why not the other way around?

RH d/s guides can be displayed in html-single or multi-page format. The UI link that got broken links to the multi-page format. The links we use throughout the docs set link to the html-single format.

I have been able to confirm that the secondary IDs work with the html-single format. It looks like the multi-page format keeps relying on the primary ID.

That's why I'd like to use the "old" ID as the primary one -- that should make the UI link work again. We can define the "new" ID (which properly matches the heading and file name) as the secondary one because that one should work with all the cross links in this docs set.

I feel the need to add that although I spent a full hour fiddling with links and IDs in our d/s docs staging area, there is still a good chance that I'm wrong, in which case this PR won't fix anything and I will need to revert back to using the "old" ID everywhere. I still think this is worth a try. Does this make sense @maximiliankolb?

I am not willing to sacrifice (for "master"!) that we have matching file names, anchors, and titles. If your PR targets 3.12, then I'd be perfectly OK; fixing this on a released version is a no-brainer to me! I use grep a lot to get around and understand things, and having any deviation really slows down this workflow.

Unfortunately, in downstream, I strictly rely on the only anchor to be in the first line. So far, there is no exception to that assumption/rule/convention in the commit from "3.11" that I currently use.

For now, a PR targeting 3.12 so that foreman-documentation does not break any links in built Foreman/Satellite plugins seems like the perfect solution. This would buy us some more time to potentially fix any "nightly" builds of Foreman/Katello plugins. cc @asteflova

asteflova commented 1 month ago

Thanks a lot @maximiliankolb! Let's continue the conversation about a more long-term solution elsewhere (one of the meetings?). I don't think that a convention for matching IDs/filenames/headings works well with deep-linking from the UI but then again, I don't know how and why the links got added like this so a conversation with the broader team would help.

asteflova commented 1 month ago

Merged to "3.12" and no cherry picks.

theforeman / foreman-documentation