update readme guidance #1359
update readme guidance #1359
Conversation
|
PTAL @maggiepint @scbedd |
|
Addresses #1214. |
|
@heaths I believe you were also interested in reviewing the guidance for links. |
docs/policies/README-TEMPLATE.md
Outdated
| @@ -22,7 +22,7 @@ Use the guidelines in each section of this template to ensure consistency and re | |||
| - [Samples](./samples) | |||
There was a problem hiding this comment.
@KarishmaGhiya can you update the links here to match the guidance.
There was a problem hiding this comment.
As well in the sample readme next to this md.
There was a problem hiding this comment.
The samples and changelog don't exist. Should we remove them from the bulleted list?
| @@ -22,7 +22,7 @@ Use the guidelines in each section of this template to ensure consistency and re | |||
| - [Samples](./samples) | |||
| - [Versioned API References](https://azure.github.io/azure-sdk-for-python/ref/Cosmos.html) -- Note this link format may be updated in the future but it is the best we have for now. | |||
|
|
|||
| * **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. | |||
| * **DO NOT** use relative links to other files in the source repository. Use links to master in all our md files in the repo as this will help ensure that links work and don't break in a lot of cases. However when we publish these to docs we have the opportunity to transform those links to use the release tags instead of the master links. | |||
There was a problem hiding this comment.
If the links are being transformed when releasing, why should they be absolute? As relative links, they not only link to the same commit (i.e. same source version instead of something that could be very different), but they also work in local clones so people browsing the source locally can navigate the files. Can you explain the benefit in using fully-qualified URLs?
There was a problem hiding this comment.
The biggest issue is that while we can and will transform the links in some workflows there are a number of other workflows that we don't have an opportunity to plug-in a step that will transform the links. I called out a couple examples in #1214.
There was a problem hiding this comment.
But then what do we do about files out of sync? Viewing a file in one commit (perhaps online, or in a local clone) will potentially link to a different commit that may work differently? Since release tags are deterministic, at least for releases can we ask/require that people use those instead?
There was a problem hiding this comment.
The guidance will definitely be to use release-tags for links when we control the pipeline for publishing them.
As for source links yes they do have the possibility to get out of sync but no matter what we do there will be some links that might get out of sync and if you are working in the scope of the repo you have a much better chance of finding and fixing links then folks in a completely different context.
I wanted us to get agreement on the guidance first and then @KarishmaGhiya is going to work on the implementation. She has already started on doing some of that work in parallel. |
I'll follow the guidance, but I don't think absolute URLs are the correct solution. Hopefully we can improve upon this later on.
No description provided.