elastic / elastic/docs-builder

[Feature Request]: Add error-checking for removal of files/URLs used by product

Open
#736 2 comments 0 reactions 0 assignees View on GitHub
ai-triaged ai:eng-question ai:product-question enhancement
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

### Prerequisites

- [x] I have searched existing issues to ensure this feature hasn't already been requested
- [x] I have tested using the latest version of docs-builder

### What problem are you trying to solve?

With the changes to the way we're handling versioning in the Docs V3, we'll have scenarios where URLs that are used in the product (for example, in error messages or logs or UIs) need to continue to exist (or have appropriate redirects) for as long as that product version is supported.

In the old documentation system, as long as the old product version was pointing to an old docs version, it didn't matter if we removed a page from the latest docs versions. That will no longer be true. We'll need to ensure that either the page persists (with version appropriate trail markers if the content moves or changes radically) or that appropriate redirects are created.

### Proposed Solution

@Mpdreamz suggested that we could add something like this:

```
locked:
- path/to/yaml
```

... And start erroring if that page is no longer available or does not redirect. That way we can ensure certain pages always resolve.

### Examples and Research

This issue arose as part of the discussion about how to handle pages that are linked from the Elasticsearch logs and error messages (https://github.com/elastic/elasticsearch/blob/main/server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt) and how to ensure that the URLs used in V9.0.0, for example, continue to exist. And in the case of version-specific troubleshooting content or performance tuning content that is likely to change over time--how to ensure that when/if version-specific page variations arise that the URLs that existed in the early releases still resolve to something appropriate.

### Alternative Solutions

Alternatively, we could add rely on (at a minimum) link checking all the link services that are used across our various product repos. The link checking would still need to run against all in-support branches of those link services.

Relates to https://github.com/elastic/docs-builder/issues/123

### Additional Context

_No response_

### How important is this feature to you?

Important

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.