Skip to content

docs: reorganise release/version docs #7033

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 5 commits into from
Jun 24, 2023
Merged

docs: reorganise release/version docs #7033

merged 5 commits into from
Jun 24, 2023

Conversation

bradzacher
Copy link
Member

@bradzacher bradzacher commented May 17, 2023 •
edited
Loading

PR Checklist

Overview

Slight cleanup / reorganisation / deduplication of the docs here

To start with - the new sidebar:

Note that "Contributing" and "Maintenance" are collapsed by default.

Sidebar Changes:

  • "Users" section to clearly group docs made for users
    • We now have these clearly user-facing docs where previously it was hidden inside the "maintenance" docs and looked like it was internal docs:
      • "Dependency Versions" explains what dependency versions we support
      • "Releases" explains when and why we do releases
      • "Versioning" explains how we classify our version bumps
  • "Developers" section to clearly group docs made for developers
    • For now just contains "Building Custom Rules" but can house more in future if we write some.
  • Renamed "Architecture" to "Packages". The former didn't really describe what it contained to me, and IMO it was super hard to find the package documentation unless you go directly via the npm package page.

You can follow the changes but I moved some sections around amongst the "User" docs to deduplicate. EG I noticed there wasn't really clear delineation between the "releases" doc and the "versioning" doc - and there was some duplication between them too.

@JamesHenry - is there any way to add a custom footer to the GH release notes?
I'd love it if we could add a link to both the "Releases" and "Versioning" pages to the release notes so that we can very clearly promote these docs.

Sorry, something went wrong.

@bradzacher bradzacher added the documentation Documentation ("docs") that needs adding/updating label May 17, 2023
@typescript-eslint
Copy link
Contributor

Thanks for the PR, @bradzacher!

typescript-eslint is a 100% community driven project, and we are incredibly grateful that you are contributing to that community.

The core maintainers work on this in their personal time, so please understand that it may not be possible for them to review your work immediately.

Thanks again!

🙏 Please, if you or your company is finding typescript-eslint valuable, help us sustain the project by sponsoring it transparently on https://opencollective.com/typescript-eslint.

@netlify
Copy link

netlify bot commented May 17, 2023 •
edited
Loading

✅ Deploy Preview for typescript-eslint ready!

Name Link
🔨 Latest commit cdf7d90
🔍 Latest deploy log https://app.netlify.com/sites/typescript-eslint/deploys/64967b3da23c7f00070b8a6a
😎 Deploy Preview https://deploy-preview-7033--typescript-eslint.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

@nx-cloud
Copy link

nx-cloud bot commented May 17, 2023 •
edited
Loading

☁️ Nx Cloud Report

CI is running/has finished running commands for commit cdf7d90. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this branch

✅ Successfully ran 25 targets

Sent with 💌 from NxCloud.

Josh-Cena
Josh-Cena reviewed May 17, 2023
View reviewed changes
Copy link
Member

@Josh-Cena Josh-Cena left a comment

Choose a reason for hiding this comment

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

Incomplete reviews. Can we also settle on a file naming convention? We seem to be using more kebab-casing (and some SCREAM_CASING) in the past.

@bradzacher
Copy link
Member Author

Can we also settle on a file naming convention? We seem to be using more kebab-casing (and some SCREAM_CASING) in the past.

The convention in /docs at least seems to be 95% Title_Snake_Case - which is what I used for new files and renamed existing files to. There are a few UPPER_SNAKE_CASE but they're dying out.

I have no preference one way or the other though. (If it were up to me I'd use camelCase or PascalCase heh)

@bradzacher
Copy link
Member Author

bradzacher commented May 17, 2023 •
edited
Loading

Build error

3:04:51 PM: [ERROR] Unable to build website for locale en.
3:04:51 PM: [ERROR] Error: Docusaurus found broken links!
3:04:51 PM: 
3:04:51 PM: Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.
3:04:51 PM: Exhaustive list of all broken links found:
3:04:51 PM: 
3:04:51 PM: - On source page path = /packages/utils:
3:04:51 PM:    -> linking to /custom-rules

Weirdly it didn't show up locally using yarn start

@Josh-Cena there were a number of times that I moved files around and then ran yarn start and it wouldn't detect broken links (where we used relative file links to other mdx files). Is this expected with yarn start and it's only guaranteed to be detected with a proper build?

bradzacher and others added 2 commits May 23, 2023 13:27
@bradzacher @Josh-Cena
Apply suggestions from code review
01a164b 
Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
@bradzacher
more docs updates
0a822f2
@bradzacher bradzacher requested a review from Josh-Cena May 23, 2023 04:43
JoshuaKGoldberg
JoshuaKGoldberg reviewed May 29, 2023
View reviewed changes
packages/website/sidebars/sidebar.base.js
'users/releases',
'users/versioning',
],
label: 'Users',
Copy link
Member

Choose a reason for hiding this comment

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

I think this is the only part of this PR I'm not 100% positive on... Everybody is a user. Is there a more precise term we can use? End Users perhaps?

Copy link
Member Author

Choose a reason for hiding this comment

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

My thinking was there are "users" which are the ones doing linting and the "developers" which are the ones building things with their tooling.

Technically the "developers" are "users" of our tooling, for sure, but I thought there might be enough distinction?

I don't love "end users"... I wonder if there's another term we can use?

JoshuaKGoldberg
JoshuaKGoldberg previously approved these changes May 29, 2023
View reviewed changes
Copy link
Member

@JoshuaKGoldberg JoshuaKGoldberg left a comment

Choose a reason for hiding this comment

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

Cartoon penguin happily saying 'primo!'

@Josh-Cena
Copy link
Member

there were a number of times that I moved files around and then ran yarn start and it wouldn't detect broken links (where we used relative file links to other mdx files). Is this expected with yarn start and it's only guaranteed to be detected with a proper build?

Yes, the broken link detection only works reliably in build. Sometimes dev also reports link errors but I can't remember in which cases (usually when it blocks rendering the correct link)

@bradzacher bradzacher merged commit cc33804 into main Jun 24, 2023
@bradzacher bradzacher deleted the clarify-release-docs branch June 24, 2023 06:03
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jul 2, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@JoshuaKGoldberg JoshuaKGoldberg

@Josh-Cena Josh-Cena

Assignees
No one assigned
Labels
documentation Documentation ("docs") that needs adding/updating
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Repo: Why the version bump to v5.59.6?
3 participants
@bradzacher @Josh-Cena @JoshuaKGoldberg