Skip to content

Update CodeQL CLI docs articles and links to point to new location on GitHub Docs site #12077

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

Merged
merged 9 commits into from
Feb 3, 2023

Conversation

saritai
Copy link
Contributor

@saritai saritai commented Feb 2, 2023

Docs-content issue: https://github.com/github/docs-content/issues/6930

These updates are a follow up to migrating all the articles under "Using the CodeQL CLI" and "CodeQL CLI reference" to the GitHub Docs site.

Changes in this PR:

  1. I've removed the content from these articles on the microsite that were migrated - and replaced it with a note that lets people know the article has been migrated and provides a link to the new location of the article. Also added mini-TOCs to each page that includes all the subsections and links to the new version of them. This allows users to quickly find a subsection they may have bookmarked! We can remove this eventually, especially once we start making changes to these articles.
  2. I have updated any links in other articles that linked to these CodeQL CLI articles to just point directly the new location of the article on the GitHub Docs site
  3. Also ended up updating the CONTRIBUTING.md file and the READMEs from the swift and go directories to update some links in there to point to the new location on GitHub Docs, for convenience.

Looks like a number of reviewing groups will be pinged on this - but just know that all of the changes (outside the codeql-cli directory) are just updating links to point to GitHub Docs.

cc @felicitymay @adityasharad

@saritai saritai changed the base branch from main to codeql-cli-2.12.2 February 2, 2023 19:16
@adityasharad
Copy link
Collaborator

How will anchor links be handled? We sometimes provide customers with specific links to anchors/sections within the docs pages. As I understand this PR, following one of those anchored links will now take the reader to the overall page with a redirect notice, but no guidance on how to find the equivalent section in the new page.

@saritai
Copy link
Contributor Author

saritai commented Feb 2, 2023

@adityasharad Ah looks like I missed some of those that didn't have the path of the page they were from! We can definitely update that link to point directly to that anchor in the new article, as we kept the same headings as were in the original articles! Let me sweep through and try to find the rest of these anchor links I didn't get 👍

@saritai
Copy link
Contributor Author

saritai commented Feb 2, 2023

@adityasharad I think I got all the anchor links - there were only a few! I found all the anchor links in these migrated articles and searched for them across this repo. Thanks for the question, great catch! 🙇‍♀️

@saritai saritai marked this pull request as ready for review February 2, 2023 21:13
@saritai saritai requested review from a team as code owners February 2, 2023 21:13
@saritai saritai requested a review from felicitymay February 2, 2023 21:13
@adityasharad
Copy link
Collaborator

@adityasharad I think I got all the anchor links - there were only a few! I found all the anchor links in these migrated articles and searched for them across this repo. Thanks for the question, great catch! 🙇‍♀️

Thanks, that looks like it covers the anchor links within the existing docs. Can we do anything more about existing anchor links that users attempt to access directly (e.g. if they recorded links in their own internal docs for reference)? Perhaps by keeping the table-of-contents list in the redirect pages, with redirect links to each section, rather than just a redirect link to the page as a whole?

Copy link
Contributor

@felicitymay felicitymay left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for finding and replacing all those links @saritai. I found one more that we should probably update.

Regarding the point about anchors that we've given to users that @adityasharad raises, I think it would be quite a lot of work to update each article with a "fake" TOC. I wonder if this is necessary because the articles on the docs site each have a mini-TOC so users ought to be able to identify the section they need fairly easily, assuming that the heading is an H2.

image

image

If we do decide that we need to do something for anchors that you use frequently, perhaps we can make a list of them so that we only add links for headings that are needed?

Copy link
Contributor

@felicitymay felicitymay left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@saritai - thank you for taking the time to add the links to all the anchors in the new location. Hopefully that'll help users find their place easily.

I spot checked some of the TOC links and they all worked perfectly 👍🏻

Copy link
Collaborator

@adityasharad adityasharad left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

@saritai saritai merged commit 8edd378 into codeql-cli-2.12.2 Feb 3, 2023
@saritai saritai deleted the codeql-cli-articles-migration-update branch February 3, 2023 20:25
@jketema
Copy link
Contributor

jketema commented Feb 3, 2023

I think this needs a merge back to main, as the post-release merge back has already happened.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants