Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update PublishRepositoryUrl in README #1270

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Update PublishRepositoryUrl in README #1270

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7b3ec58
Update PublishRepositoryUrl in README
MattKotsenas Aug 28, 2024
60a09b5
break 'debugging' into three pieces and refactor
MattKotsenas Aug 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 12 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,19 +18,24 @@ Starting with .NET 8, Source Link for the following source control providers is
- [GitLab](https://gitlab.com) 12.0+ (for older versions see [GitLab settings](#gitlab))
- [Bitbucket](https://bitbucket.org/) 4.7+ (for older versions see [Bitbucket settings](#bitbucket))

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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we need to separate the properties from the PackageReferences in the project snippet.

Copy link
Member Author

@MattKotsenas MattKotsenas Aug 28, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

#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!

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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:

  1. Embedding source information into the PDB
  2. Adding source information into the .nuspec
  3. 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
  • .nuspec information is controlled by <PublishRepositoryUrl>

@tmat let me know what you think. Very happy to hear and include your feedback. Thanks!


```xml
<Project>
<PropertyGroup>
<!-- Optional: Publish the repository URL in the built .nupkg (in the NuSpec <Repository> element) -->
<!-- Publish the repository URL in the built .nupkg (in the NuSpec <repository> element) -->
<PublishRepositoryUrl>true</PublishRepositoryUrl>

<!-- Optional: Embed source files that are not tracked by the source control manager in the PDB -->
<!-- Optional (set by default in .NET SDK 8+): Embed source files that are not tracked by the source control manager in the PDB -->
<EmbedUntrackedSources>true</EmbedUntrackedSources>
</PropertyGroup>
</Project>
```

If your project does not yet use .NET SDK 8+, or is not hosted by one of the above providers, you must also add a PackageReference to a Source Link package specific to the provider:

```xml
<Project>
<ItemGroup>
<!-- Add PackageReference specific for your source control provider (see below) -->
</ItemGroup>
Expand All @@ -39,8 +44,10 @@ If your project uses .NET SDK 8+ and is hosted by the above providers it does no

Source Link packages are currently available for the source control providers listed below.

> [!TIP]
> Source Link package is a development dependency, which means it is only used during build. It is therefore recommended to set `PrivateAssets` to `all` on the package reference. This prevents consuming projects of your nuget package from attempting to install Source Link.

> [!NOTE]
> Referencing any Source Link package in a .NET SDK 8+ project suppresses Source Link that is included in the SDK.

### github.com and GitHub Enterprise
Expand Down