Determine best guideline for links in our READMEs

[weshaggard]

We need to update our guidelines about how to best prevent broken links for our README's and other md files that we publish to multiple locations.

https://github.com/Azure/azure-sdk/blob/master/docs/policies/README-TEMPLATE.md

DO use relative links to other files in the source repository. Relative links will be converted to absolute links using the commit sha reference during publishing, that will ensure that we don't break links when we move things around in the repo in the future. So avoid using absolute links to a branch like master as they will definitely be broken in the future.

Currently the guidelines were to use relative links to things in source with the goal that they would always work on github and we would a tool relative-link-replacer whiche we would run before we published them anywhere to turn links in to permalinks. However we have found a number of issues with this approach:

1. It requires that files included in packages get mutated from what is committed before they are packaged. While maybe not a big deal for all ecosystems it becomes interesting for ecosystems like python where they expect to be able to install a package from github using a release tag and have it match exactly what is on pypi which isn't the case if we mutate it before we publish to pypi.

2. There are a number of places our MD files are consumed and some which we do not even control which pull these files and so we don't have a place to run our step that updates the links.

Based on those there isn't any great solution beyond always using links to master (or the branch they are contained) in as the static committed state. However we also know that using links to master tend to break overtime so it is probably worth replacing those master links to permalinks in workflows we do control to help them continue working overtime.

Even with the permalinks it is generally better to use release tags instead of commit sha, because the links generally shorter and look better and give flexibility to change them in the future if needed. However the trouble is a lot of this link updating happens before the release tag is created so we either have to blindly use it in the hope that it will be created in the future or we have to stick with the commit sha for the link.

cc @maggiepint @scbedd @KarishmaGhiya

[heaths]

Also consider how samples' READMEs are impacted. Currently, the guidance is for absolute URLs (or so I'm told - didn't actually find such guidelines) but that would lead people off the samples browser back to GitHub. We should also strive to minimize site-hopping as directs people off the site they were using - which probably has more information about what they want, like docs.microsoft.com - and gets them lost in navigation.

[weshaggard]

Guidance updated with #1359