diff --git a/docs/contributing/use-reliable-links.md b/docs/contributing/use-reliable-links.md new file mode 100644 index 00000000000000..8573b10c43faac --- /dev/null +++ b/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/", "destination": "", "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/` 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