PSA about `core-js`'s `README`

[Rudxain]

This is an "alert" or announcement that it's extremely likely that some links to the README.md file at the Core JS repo will break in the near future. This is because of this PR that solves the Issue of the file being too big. We're trying our best to preserve external links (avoid breaking them), but some links will inevitably break (usually "inner" ones, the ones that point to very nested sections).

I opened this issue not only to notify, but to get some feedback. I (and "we", but mostly "I") can't read the entire MDN, so I can't know if a link that "looks unimportant" is actually very important and frequently used. Please let us know of any mistakes we're doing while moving sections. Thank you all for your time & patience. I hope you understand

Note: I don't know if I used the acronym "PSA" correctly. English is not my main language

[teoli2003]

Thanks for the head-up.

I see 235 links from MDN. I think having them fixed, though a significant amount of work, is doable.

Ideally, we could minimize the amount of time the links on MDN are broken.

Will there be a way to predict the new link from the old link so we can prepare the PR and be ready when the change happens (that way shouldn't have a link broken for more than 24 hours)? Or will we have to wait for the new links to be live and update them then (Given we have 235 links to fix, it will likely take more time there, unless the community can give a hand there)?

[Rudxain]

Will there be a way to predict the new link from the old link?

Good question. The exact details about the current plan are somewhat ambiguous, but most links will follow a pattern that would look like this: /README.md#section -> /docs/Section.md and inner sections would be in deeper folders, looking like /docs/Category/Sub%20Section.md, and deeper ones would be /docs/Category/Sub%20Section.md#sub-sub-section

I'm currently (not necessarily always) the main contributor to the PR, not the original repo owner, so I would recommend asking questions to @zloirock

Small clarification: I opened this issue on my own, and nobody has told me what to say or do. I only recieved instructions about the PR itself (because I'm not the owner and I requested guidance, to avoid wasted work)

[Rudxain]

I forgot to say that links to main sections won't be broken, but will act as a "manual redirect". This means there's no need to fix links to "outer sections", but it's recommended if there's a need to point directly to the actual content, instead of having users click the redirection

[Rudxain]

I'll prepare a model for how I plan to structure the directory tree, then I'll edit the main (1st) PR comment to include the model. That way, it'll be easier for everyone to prepare and suggest changes before I even make them.

About the plan, it'll be divided in 2 main stages (which may be subdivided into more stages):

1. 1st stage consists of moving content from the README to /docs. This stage will be "officially complete" once everything has been moved and we verify that internal links work correctly.
2. 2nd stage will be the "final touches", and will consist on editing and adding some content to the docs themselves, in such a way that shouldn't affect the links. This stage will add indexes and maybe some images and extra files.

After 1st stage, everyone would probably have enough time to prepare for the update (when the PR is merged). If not, we'll delay merging the PR. That would probably be the case since other websites also have links pointing to the README.

Please keep in mind that I'm not "in charge" of this process, nor the plan, nor the stages. What I said is what I think it's "best", but may be subject to change and improvement by zloirock and contributors

[zloirock]

I don't think that renaming by a pattern is a good idea. I think that the changing of the structure of core-js docs is a good chance to fix some sections that I didn't change to save existing links.

[Rudxain]

I don't think that renaming by a pattern is a good idea

Just to clarify, I didn't meant using a regex. But I think I get what you mean, a pattern (by definition) is something that repeats and doesn't "break", but not all links have to follow the same pattern

[Rudxain]

Added dir tree model: zloirock/core-js#1095 (comment)

[Rudxain]

Good news! I found a way to find all (I guess) headings easily. This means inner links won't break, but will now redirect to their corresponding doc files

[Josh-Cena]

Hi, I'm going to close this since there doesn't seem to be much solid progress on the core-js README so there's nothing for us to act on. The MDN team is aware of this change and will be cooperating once the change lands, but we will wait for another signal. For example, when Denis changed his README to the open letter, we almost instantly got many pull requests updating the URL. It will suffice if one of you pings me under this issue (if the change lands within one year from now) or sends another issue (if it happens far into the future).