Proposal for a policy to not remove anchors from stable versions

[ekohl]

I was thinking about a policy to prevent breakages and initially came up with the following text:

In a released version the anchors should never be removed. This is needed because applications like Foreman may refer to it and users may have bookmarked them.

In downstream Red Hat has the multi-HTML view where it may lead to 404s errors because of URL changes. That may also affect SEO because AFAIK we don't create redirects.

The background is that Foreman itself can link to documentation. It has various helpers for this. Today many of these still point to the existing Foreman manual, but I'd still love to migrate to docs.theforeman.org (https://github.com/theforeman/foreman-documentation/milestone/3).

If the application links to some section, it usually does so via an anchor. Changing those will break the application for users.

For Satellite we also have foreman_theme_satellite which rewrites them. These already refer to more anchors and there is some automation to check links against the table of contents.

In case a rename must happen (and experience tells me, there usually is something) then we can use auxiliary IDs. This is also supported by the DITA migration (jhradilek/asciidoctor-dita-vale#155).

[apinnick]

I think auxiliary IDs are a good idea for persistent links. They are less likely to be changed or removed by accident.

We use auxiliary IDs for OpenShift Virt docs, preceded by a comment: // Do not delete. Used by UI.

[Lennonka]

Is there a way to extract the used anchors from code and used it for an automated check in PRs?

[ekohl]

Is there a way to extract the used anchors from code and used it for an automated check in PRs?

It would really help a lot if we could automatically verify all used links resolve but I can't think of an easy way. The best I can think of is to scan all code bases in a similar way as how we extract all translation strings.

[maximiliankolb]

Is there a way to extract the used anchors from code and used it for an automated check in PRs?

AFAIK there's something like that in foreman_satellite_theme already. See https://github.com/RedHatSatellite/foreman_theme_satellite/blob/develop/test/link_checker.rb

For orcharhino downstream, I have a similar check that "clicks" on all documentation buttons and checks if they work.

Overall, I like this proposal. However, I have some questions/concerns too.

• Why not fix it in code? upstream/downstream projects could just publish errata.
• Is that something we should start doing after DITAfication which is almost done?
• I like the idea to not break anchors, but I am strongly against a practise of never ever changing/fixing anchors again. So we must not use this argument to not fix any anchors.
• We must not accumulate endless lists of historical anchors. We could write a script that runs after branching the docs and drops all auxiliary IDs. Then, upstream/downstream would still have plenty of time to fix their links in code.
• About SEO: Antora has a way to define page aliases which is often helpful. I imagine that there's something similar to anchors and/or other platforms too.

[ekohl]

AFAIK there's something like that in foreman_satellite_theme already. See https://github.com/RedHatSatellite/foreman_theme_satellite/blob/develop/test/link_checker.rb

It relies on the entries that are explicitly listed (https://github.com/RedHatSatellite/foreman_theme_satellite/blob/develop/lib/foreman_theme_satellite/documentation.rb), but that list is incomplete and can easily go out of sync.

Why not fix it in code? upstream/downstream projects could just publish errata.

You don't know if the customer has installed the latest errata. Many of them have policies that they can only apply them in certain maintenance windows. Overall it can easily be a month or 2 because it's really applied and during that time it's broken.

Is that something we should start doing after DITAfication which is almost done?

IMHO it's something that should be done before DITAfication. DITA must not break existing applications.

I like the idea to not break anchors, but I am strongly against a practise of never ever changing/fixing anchors again. So we must not use this argument to not fix any anchors.

Note I explicitly mentioned stable versions. In development they can be changed as long as we make sure the application is also updated.

We must not accumulate endless lists of historical anchors. We could write a script that runs after branching the docs and drops all auxiliary IDs. Then, upstream/downstream would still have plenty of time to fix their links in code.

I think that makes sense.

About SEO: Antora has a way to define page aliases which is often helpful. I imagine that there's something similar to anchors and/or other platforms too.

To me it's still an interesting idea to use Antora in upstream, but I wouldn't want to build redirects myself here in upstream.

[Lennonka]

This is a valid request, but we need to figure out how the writer will know that the anchor they are changing is linked from the web UI. Let's not include auxiliary IDs for everything.

We can either:

• Include comments before linked IDs as Avital suggested.
• Automate the check as I suggested.
• Other options?

[ekohl]

This is a valid request, but we need to figure out how the writer will know that the anchor they are changing is linked from the web UI. Let's not include auxiliary IDs for everything.

I was suggesting to only add auxiliary IDs in stable branches in the rare case that you need to rename a section. Since they're only done in the cherry picks and don't show up in the master branch I'm not worried about them sprawling and sticking around forever.

It does mean you need to be more careful when cherry picking.

[Lennonka]

you need to be more careful when cherry picking

That sounds like a huge pain in the ass for maintainers.

[ekohl]

It probably is, but I wonder how else you're going to guarantee you don't break the integration? I don't disagree we need some automation to help here, but in the end there is an integration between the docs and the application so there needs to be collaboration from both sides. And users may have bookmarked individual sections so it's also friendly to them.

[Lennonka]

I just think it would help to add the auxiliary IDs on master. Then they would get cherry picked by default. No fuss.

[ekohl]

Also works for me, but then you need to remember to remove them as well. I have less of an opinion on those specifics.

[ekohl]

A concrete example that this broke: 5fcb4c4#diff-09a5b21ea42021efa15bd3d3e9ee295c052750553a4def91f9f78bbf5f58984f. I'm not sure if this could have been caught while reviewing #4608.

Today upstream isn't affected, but if we would use the new docs as the default then we would have been affected.

[Lennonka]

Also works for me, but then you need to remember to remove them as well.

My point is that forgetting to remove them would do less damage than forgetting to add them 😆

Let's figure out how we will know when to add them, ie. how we will know when we're about to break something.
We already have to remember so many requirements for docs that I strongly recommend finding an automated check for PRs.

[ekohl]

My point is that forgetting to remove them would do less damage than forgetting to add them 😆

And it's a great point.

We already have to remember so many requirements for docs that I strongly recommend finding an automated check for PRs.

Thinking out loud: somehow enhance the PR preview? Ther's to build the table of contents (https://github.com/theforeman/foreman-documentation/blob/master/guides/scripts/extract_links_toc) so perhaps we can generate additional files:

• toc-base.json
• toc-pr.json
• toc.diff (if there is a diff)

Perhaps the diff can also be smarter in that it should only warn about removed items in the ToC because adding new ones is no risk for cherry picks.

It's up to the team, but you can also consider automating adding labels or something to assist.

[Lennonka]

I'm imagining something like this:

    extract links        extract_links_toc
   from Foreman UI          from PR
           \_                _/
             \_            _/
               \_        _/
           attempt to find UI link      <-------- Repeat
               in toc-pr.json                    |
              /              \                   |
             /                \                  | 
       Link found         Link not found         |
           |                    |                |
         Noop                Report              |
             \              /                    |
               -----------------------------------

But I have no idea how to extract links from Foreman web UI.
That's where you come in, @ekohl 😁
Shall we explore the plausibility of extraction in more detail?