Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PSA about core-js's README #17561

Closed
Rudxain opened this issue Jun 22, 2022 · 9 comments
Closed

PSA about core-js's README #17561

Rudxain opened this issue Jun 22, 2022 · 9 comments
Labels
Content:Other Any docs not covered by another "Content:" label on hold Waiting on something else before this can be moved forward.

Comments

@Rudxain
Copy link
Contributor

Rudxain commented Jun 22, 2022

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

@github-actions github-actions bot added the needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened. label Jun 22, 2022
@teoli2003 teoli2003 removed the needs triage Triage needed by staff and/or partners. Automatically applied when an issue is opened. label Jun 23, 2022
@teoli2003
Copy link
Contributor

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
Copy link
Contributor Author

Rudxain commented Jun 23, 2022

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
Copy link
Contributor Author

Rudxain commented Jun 23, 2022

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
Copy link
Contributor Author

Rudxain commented Jun 23, 2022

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
Copy link
Contributor

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
Copy link
Contributor Author

Rudxain commented Jun 23, 2022

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
Copy link
Contributor Author

Rudxain commented Jun 23, 2022

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

@Josh-Cena Josh-Cena added the Content:JS JavaScript docs label Jul 1, 2022
@Rudxain
Copy link
Contributor Author

Rudxain commented Jul 13, 2022

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 Josh-Cena added Content:Other Any docs not covered by another "Content:" label and removed Content:JS JavaScript docs labels Nov 9, 2022
@Josh-Cena
Copy link
Member

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).

@Josh-Cena Josh-Cena added the on hold Waiting on something else before this can be moved forward. label Jun 27, 2023
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 1, 2024
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Content:Other Any docs not covered by another "Content:" label on hold Waiting on something else before this can be moved forward.
Projects
None yet
Development

No branches or pull requests

4 participants