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.
• 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.

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

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 and dart-lang/site-www/firebase.json.

If an appropriate tooling redirect doesn't exist already, create one following these steps:

1. Open the firebase.json file 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.