Update PublishRepositoryUrl in README #1270
Conversation
|
@tmat, would you mind taking a look when you get a chance? If you have any questions or concerns, please let me know. Thanks! |
README.md
Outdated
| If your project uses .NET SDK 8+ and is hosted by the above providers it does not need to reference any Source Link packages or set any build properties. | ||
|
|
||
| **Otherwise**, you can enable Source Link experience in your project by setting a few properties and adding a PackageReference to a Source Link package specific to the provider: | ||
| You can enable the Source Link experience in your project by opt-ing in to publish repository information: |
There was a problem hiding this comment.
I think the previous wording was better. PublishRepositoryUrl is not necessary to enable Source Link experience. It's only needed to publish URL to nupkg.
There was a problem hiding this comment.
Perhaps we need to separate the properties from the PackageReferences in the project snippet.
There was a problem hiding this comment.
I think the previous wording was better.
PublishRepositoryUrlis not necessary to enable Source Link experience. It's only needed to publish URL to nupkg.
#1203 is evidence that users are confused by the current wording. Maybe the next step would be to clarify what Source Link experience users get without setting PublishRepositoryUrl, as it isn't clear to me either.
Perhaps we need to separate the properties from the PackageReferences in the project snippet.
That was my intention with this change. Can you clarify what changes you'd like to see here, and I'll be happy to make them. Thanks!
There was a problem hiding this comment.
@tmat, I thought about this more and I think I came up with a better framing. I made a small addition to the opening section to capture that what we (I?) think of as "Source Link" is three components:
- Embedding source information into the PDB
- Adding source information into the .nuspec
- Distributing PDBs
1 and 2 coupled in the current version of the docs, which is what lead to confusion in the linked bug. Currently, the docs make it look to some readers that in .NET 8+, 1 and 2 happen automatically, but only 1 happens automatically. The previous version of this PR made it sound like 1 and 2 are both controlled by <PublishRepositoryUrl>, which isn't true either.
Now I think it's clearer that:
- 1 is controlled by including the package (or using a new SDK)
- I also moved the
<EmbedUntrackedSources>suggestion to this part as well, since it's coupled to the SDK decision and independent of the NuGet part
- I also moved the
- .nuspec information is controlled by
<PublishRepositoryUrl>
@tmat let me know what you think. Very happy to hear and include your feedback. Thanks!
MattKotsenas
force-pushed
the
bugfix/docs-publish-repo-url
branch
from
15dc2bb
to
60a09b5
Compare
|
@tmat would you mind taking another look here? Thanks! |
Fixes #1203.
<PublishRepositoryUrl>is still an opt-in setting, even in .NET SDK 8+<EmbedUntrackedSources>is true by default in .NET SDK 8+[!TIP]and[!NOTE]to better highlight caveats about referencing Source Link