docs: rework docs around errors (#11802)

* docs: rework docs around errors * Update packages/astro/src/core/errors/README.md Co-authored-by: Chris Swithinbank <[email protected]> * docs: expand deprecation description --------- Co-authored-by: Chris Swithinbank <[email protected]>
withastro · Sep 2, 2024 · 39d330f · 39d330f
1 parent 645f4e2
commit 39d330f
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 92 deletions.
diff --git a/packages/astro/src/core/errors/README.md b/packages/astro/src/core/errors/README.md
@@ -21,8 +21,8 @@ Message:
 
 - Begin with **what happened** and **why**. (ex: `Could not use {feature} because Server-side Rendering is not enabled.`)
 - Then, **describe the action the user should take**. (ex: `Update your Astro config with `output: 'server'` to enable Server-side Rendering.`)
-- Although this does not need to be as brief as the `title`, try to keep sentences short, clear and direct to give the reader all the necessary information quickly as possible.
-- Instead of writing a longer message, consider using a `hint`.
+- Although this does not need to be as brief as the `title`, try to keep sentences short, clear and direct to give the reader all the necessary information quickly as possible. Users should be able to skim the message and understand the problem and solution.
+- If your message is too long, or the solution is not guaranteed to work, use the `hint` property to provide more information.
 
 Hint:
 
@@ -44,10 +44,10 @@ If you are unsure about anything, ask [Erika](https://github.com/Princesseuh)!
 
 ### Shape
 
-- **Names are permanent**, and should never be changed, nor deleted. Users should always be able to find an error by searching, and this ensures a matching result. When an error is no longer relevant, it should be deprecated, not removed.
+- **Names are permanent**, and should never be changed. Users should always be able to find an error by searching, and this ensures a matching result.
 - Contextual information may be used to enhance the message or the hint. However, the code that caused the error or the position of the error should not be included in the message as they will already be shown as part of the error.
 - Do not prefix `title`, `message` and `hint` with descriptive words such as "Error:" or "Hint:" as it may lead to duplicated labels in the UI / CLI.
-- Dynamic error messages must use the following shape:
+- Dynamic error messages **must** use the following shape:
 
 ```js
 message: (arguments) => `text ${substitute}`;
@@ -69,8 +69,9 @@ Here's how to create and format the comments:
 /**
  * @docs <- Needed for the comment to be used for docs
  * @message <- (Optional) Clearer error message to show in cases where the original one is too complex (ex: because of conditional messages)
- * @see <- List of additional references users can look at
+ * @see <- (Optional) List of additional references users can look at
  * @description <- Description of the error
+ * @deprecated <- (Optional) If the error is no longer relevant, when it was removed and why (see "Removing errors" section below)
  */
 ```
 
@@ -89,6 +90,19 @@ Example:
 
 The `@message` property is intended to provide slightly more context when it is helpful: a more descriptive error message or a collection of common messages if there are multiple possible error messages. Try to avoid making substantial changes to existing messages so that they are easy to find for users who copy and search the exact content of an error message.
 
+### Removing errors
+
+If the error cannot be triggered at all anymore, it can deprecated by adding a `@deprecated` tag to the JSDoc comment with a message that will be shown in the docs. This message is useful for users on previous versions who might still encounter the error so that they can know that upgrading to a newer version of Astro would perhaps solve their issue.
+
+```js
+/**
+ * @docs
+ * @deprecated Removed in Astro v9.8.6 as it is no longer relevant due to...
+ */
+```
+
+Alternatively, if no special deprecation message is needed, errors can be directly removed from the `errors-data.ts` file. A basic message will be shown in the docs stating that the error can no longer appear in the latest version of Astro.
+
 ### Always remember
 
 Error are a reactive strategy. They are the last line of defense against a mistake.
@@ -99,5 +113,7 @@ While adding a new error message, ask yourself, "Was there a way this situation
 
 ## Additional resources on writing good error messages
 
+- [Compiler errors for humans](https://elm-lang.org/news/compiler-errors-for-humans)
 - [When life gives you lemons, write better error messages](https://wix-ux.com/when-life-gives-you-lemons-write-better-error-messages-46c5223e1a2f)
-- [RustConf 2020 - Bending the Curve: A Personal Tutor at Your Fingertips by Esteban Kuber](https://www.youtube.com/watch?v=Z6X7Ada0ugE) (part on error messages starts around 19:17)
+- [RustConf 2020 - Bending the Curve: A Personal Tutor at Your Fingertips by Esteban Kuber](https://www.youtube.com/watch?v=Z6X7Ada0ugE)
+- [What's in a good error](https://erika.florist/articles/gooderrors) (by the person who wrote this document!)
diff --git a/packages/astro/src/core/errors/errors-data.ts b/packages/astro/src/core/errors/errors-data.ts
@@ -33,25 +33,7 @@ export const UnknownCompilerError = {
 	title: 'Unknown compiler error.',
 	hint: 'This is almost always a problem with the Astro compiler, not your code. Please open an issue at https://astro.build/issues/compiler.',
 } satisfies ErrorData;
-// 1xxx and 2xxx codes are reserved for compiler errors and warnings respectively
-/**
- * @docs
- * @see
- * - [Enabling SSR in Your Project](https://docs.astro.build/en/guides/server-side-rendering/)
- * - [Astro.redirect](https://docs.astro.build/en/reference/api-reference/#astroredirect)
- * @description
- * The `Astro.redirect` function is only available when [Server-side rendering](/en/guides/server-side-rendering/) is enabled.
- *
- * To redirect on a static website, the [meta refresh attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) can be used. Certain hosts also provide config-based redirects (ex: [Netlify redirects](https://docs.netlify.com/routing/redirects/)).
- * @deprecated Deprecated since version 2.6.
- */
-export const StaticRedirectNotAvailable = {
-	name: 'StaticRedirectNotAvailable',
-	title: '`Astro.redirect` is not available in static mode.',
-	message:
-		"Redirects are only available when using `output: 'server'` or `output: 'hybrid'`. Update your Astro config if you need SSR features.",
-	hint: 'See https://docs.astro.build/en/guides/server-side-rendering/ for more information on how to enable SSR.',
-} satisfies ErrorData;
+
 /**
  * @docs
  * @see
@@ -302,21 +284,6 @@ export const InvalidGetStaticPathsReturn = {
 	hint: 'See https://docs.astro.build/en/reference/api-reference/#getstaticpaths for more information on getStaticPaths.',
 } satisfies ErrorData;
 
-/**
- * @docs
- * @deprecated Deprecated since Astro 4.0. The RSS helper no longer exists with an error fallback.
- * @see
- * - [RSS Guide](https://docs.astro.build/en/guides/rss/)
- * @description
- * `getStaticPaths` no longer expose an helper for generating a RSS feed. We recommend migrating to the [@astrojs/rss](https://docs.astro.build/en/guides/rss/#setting-up-astrojsrss)integration instead.
- */
-export const GetStaticPathsRemovedRSSHelper = {
-	name: 'GetStaticPathsRemovedRSSHelper',
-	title: 'getStaticPaths RSS helper is not available anymore.',
-	message:
-		'The RSS helper has been removed from `getStaticPaths`. Try the new @astrojs/rss package instead.',
-	hint: 'See https://docs.astro.build/en/guides/rss/ for more information.',
-} satisfies ErrorData;
 /**
  * @docs
  * @see
@@ -732,28 +699,6 @@ export const NoImageMetadata = {
 	hint: 'This is often caused by a corrupted or malformed image. Re-exporting the image from your image editor may fix this issue.',
 } satisfies ErrorData;
 
-/**
- * @docs
- * @deprecated This error is no longer Markdown specific and as such, as been replaced by `ImageNotFound`
- * @message
- * Could not find requested image `IMAGE_PATH` at `FULL_IMAGE_PATH`.
- * @see
- * - [Images](https://docs.astro.build/en/guides/images/)
- * @description
- * Astro could not find an image you included in your Markdown content. Usually, this is simply caused by a typo in the path.
- *
- * Images in Markdown are relative to the current file. To refer to an image that is located in the same folder as the `.md` file, the path should start with `./`
- */
-export const MarkdownImageNotFound = {
-	name: 'MarkdownImageNotFound',
-	title: 'Image not found.',
-	message: (imagePath: string, fullImagePath: string | undefined) =>
-		`Could not find requested image \`${imagePath}\`${
-			fullImagePath ? ` at \`${fullImagePath}\`.` : '.'
-		}`,
-	hint: 'This is often caused by a typo in the image path. Please make sure the file exists, and is spelled correctly.',
-} satisfies ErrorData;
-
 /**
  * @docs
  * @see
@@ -1140,22 +1085,6 @@ export const MissingMiddlewareForInternationalization = {
 		"Your configuration setting `i18n.routing: 'manual'` requires you to provide your own i18n `middleware` file.",
 } satisfies ErrorData;
 
-/**
- * @deprecated
- * @docs
- * @description
- * The user tried to rewrite using a route that doesn't exist, or it emitted a runtime error during its rendering phase.
- */
-export const RewriteEncounteredAnError = {
-	name: 'RewriteEncounteredAnError',
-	title:
-		"Astro couldn't find the route to rewrite, or if was found but it emitted an error during the rendering phase.",
-	message: (route: string, stack?: string) =>
-		`The route ${route} that you tried to render doesn't exist, or it emitted an error during the rendering phase. ${
-			stack ? stack : ''
-		}.`,
-} satisfies ErrorData;
-
 /**
  * @docs
  * @description
@@ -1553,20 +1482,6 @@ export const ContentSchemaContainsSlugError = {
 	hint: 'See https://docs.astro.build/en/guides/content-collections/ for more on the `slug` field.',
 } satisfies ErrorData;
 
-/**
- * @docs
- * @message A collection queried via `getCollection()` does not exist.
- * @deprecated Collections that do not exist no longer result in an error. A warning is given instead.
- * @description
- * When querying a collection, ensure a collection directory with the requested name exists under `src/content/`.
- */
-export const CollectionDoesNotExistError = {
-	name: 'CollectionDoesNotExistError',
-	title: 'Collection does not exist',
-	message: (collectionName: string) =>
-		`The collection **${collectionName}** does not exist. Ensure a collection directory with this name exists.`,
-	hint: 'See https://docs.astro.build/en/guides/content-collections/ for more on creating collections.',
-} satisfies ErrorData;
 /**
  * @docs
  * @see