bug(v1): Old docs remain in the gh-pages branch

[yangshun]

🐛 Bug Report

The page "Converting Mutations" was removed from the docs but it still shows up in the Algolia results (search for mutation) can still publicly accessible at https://relay.dev/docs/en/converting-mutations.

I suspect the deploy command is doing a merge with the existing files in the gh-pages branch and not removing the old files which no longer exist.

Update: That's not the reason. Perhaps the relay-classic version is unrecognized by the versioning script. The build artifacts look really odd for classic version.

cc @endiliey

Have you read the Contributing Guidelines on issues?

Yes

To Reproduce

Go to https://relay.dev/docs/en/converting-mutations

Expected behavior

404

Actual Behavior

Page loads

Reproducible Demo

https://relay.dev/docs/en/converting-mutations

https://github.com/facebook/relay/tree/gh-pages/docs/en/converting-mutations still exists.

[endiliey]

Its not a bug. Its already by design. I have mentioned it so many times that v1 versioning fallback functionality is like this 😂😂 and I think a lot of people are still unaware of it. Thats why I have been advocating the v2 snapshot versioning so many times.

Imagine that this is your first new site. We have two docs, foo/bar.md and hello.md

When we cut our first version 1.0.0, this is whats happening. It creates the very first fallback docs

No matter what happen in the future, this foo/bar.md and hello.md will always continue to exist in every version. Its called fallback.

Edit:
Its never been possible in v1 versioning to have different set of docs in different version. The new version docs will always be the old version docs + (the new set of docs - similar set of docs (same id in new & old docs))

[endiliey]

Another scenario is https://relay.dev/docs/en/classic-guides-containers

and
https://relay.dev/docs/en/v7.0.0/classic-guides-containers

Relay-classic docs will always remain to every future version.

This is already by design, and the fix is definitely a major breaking change. Why not migrate relay to v2 ? Although It has languages enabled, it only enable 1 language which is english 😱

[yangshun]

Oh hmm. Shouldn't the fallback only kick in if it can't find the docs in the current versioned_docs folder? The versioned_sidebar should be the source of truth for a version.

[endiliey]

Not every docs is bounded to a sidebar.

Even https://single-spa.js.org/docs/faq/ intentionally dont want a sidebar.

I can find lot of other cases like this.
Its by design, and unfortunately I am not the designer of the fallback functionality

[endiliey]

Babel for example has a lot of it

The high level docs is here https://babeljs.io/docs/en/7.0.0/plugins

and a lot of the ad-hoc docs is not bound to a sidebar (intentionally)
https://babeljs.io/docs/en/7.0.0/babel-plugin-transform-member-expression-literals

[aldeed]

I have submitted a PR with a non-breaking change that resolves this issue if you opt in by configuring it. #2955