Add a contribution doc on using reliable links in tooling (flutter#150962)

The final piece of flutter/website#10363 now that most existing relevant links have been updated to use the new redirects.

Author: parlough

docs/contributing/use-reliable-links.md

@@ -0,0 +1,105 @@
+## Use reliable links
+
+If you would like to link to a website,
+do your best to link to a reliable link destination,
+sometimes known as a permalink.
+
+Even if you update the link in the repo if it changes or breaks,
+outdated versions might remain in older versions of tools, docs, etc.
+Sometimes the link destination itself can add an appropriate redirect,
+but sometimes it can't and other times it's destination is not the best choice.
+
+- If you're not sure if you need a more reliable link,
+  check out [Situations to consider](#situations-to-consider).
+- If your destination does not already have a stable link,
+  and you think it would benefit from one,
+  follow the instructions in [Create a reliable link](#create-a-reliable-link).
+
+### Situations to consider
+
+There are many linking situations that could benefit from a more
+stable/reliable redirect with a memorable URL.
+For reference, the following are a few situations where
+they can have a high impact:
+
+- Output from CLI tools like `flutter` and `dart`
+- Comments or prose in files generated by tools like `flutter create`
+- API docs in the framework or other bundled packages
+- Error messages and other diagnostics from the engine, framework, or
+  other Flutter-team maintained packages
+- Troubleshooting links from DevTools and editors
+
+> [!TIP]
+> Links that would lead to fragments on the Dart and Flutter sites
+> should often be replaced with a custom reliable link.
+> Browsers don't send URI fragments to the server,
+> so redirecting them needs extra client-side handling.
+
+
+### Create a reliable link
+
+If you need a reliable link, consider
+adding a tooling redirect to the Flutter documentation site,
+and using that in place of the intended destination.
+Tooling redirects are added in a similar fashion to design-doc go links,
+and the website team will do their best to keep it functional.
+Once created, a tooling redirect is accessed through a link like
+starting with `/to/`, such as `flutter.dev/to/gesture-disambiguation`.
+
+Before creating a new tooling link,
+verify that an appropriate one doesn't exist already.
+To see what redirects exist already, check the `/to/` entries in
+[`flutter/website/firebase.json`][flutter-redirects] and
+[`dart-lang/site-www/firebase.json`][dart-redirects].
+
+If an appropriate tooling redirect doesn't exist already,
+create one following these steps:
+
+ 1. Open the [`firebase.json` file][flutter-redirects] in the
+    `flutter/website` repository and edit it using the GitHub UI or locally.
+ 2. Determine a short, relevant, and memorable name for the redirect.
+    No special characters are allowed and under 5 words is preferred.
+    Remember users might need to type it manually, or it might be output
+    in a crowded terminal or UI.
+ 3. Convert the name to a `lowercase-with-dashes` format and fill out
+    a redirect entry in the following format with it and the destination URL:
+
+    ```json
+    { "source": "/to/<redirect-name>", "destination": "<url>", "type": 301 }
+    ```
+
+    Note that if you are linking to the Flutter docs site itself,
+    don't include the origin of the destination URL, just the path.
+ 4. Place this entry with the other tooling (`/to/`) redirects in the file
+    according to its alphanumerical sorting.
+    Certain editors can sort a selected portion of the redirects as well.
+ 5. Commit your changes, push them if needed, and open a new pull request
+    against the `flutter/website` repository's `main` branch.
+ 6. Set a descriptive pull request title, similar to the following:
+
+    ```markdown
+    Add a `/to/<redirect-name>` tooling redirect
+    ```
+ 7. In the pull request description, include a link to the PR, CL, or
+    wherever else that will make use of the redirect, as well as
+    what project team can be reached out to if it needs to be updated.
+ 8. Unless a website maintainer has feedback about the
+    redirect name, usefulness, destination, or formatting,
+    they will approve and land the change for you.
+ 9. Once your tooling redirect has landed,
+    switch to using the tooling redirect wherever needed.
+10. The website maintainers might reach out to you
+    if the redirect needs to be updated, but do consider
+    checking your redirects occasionally to verify they still make sense.
+
+> [!IMPORTANT]
+> There is a maintenance cost of a tooling redirect,
+> both for your team and the website maintainers.
+>
+> So if the link is being surfaced in a way or location
+> that users will quickly see an updated version,
+> a tooling redirect might not be necessary.
+> The same goes for links that are only needed for a short time.
+
+[flutter-redirects]: https://github.com/flutter/website/blob/main/firebase.json
+[dart-redirects]: https://github.com/dart-lang/site-www/blob/main/firebase.json