Package descriptions for CSharp and VB should include summary blurb #22166

jcouv · 2017-09-18T15:59:04Z

Customer scenario

Find the compiler packages to add to your project on nuget.org or myget.org (for example CodeAnalysis.CSharp). The package description should give you a summary and a link to our package documentation (including versioning).
But currently, many packages only show a commit link.

Also, I'm removing the summary section since it does not seem to appear anywhere.

Correct:

Incorrect:

Workarounds, if any

This does not block usage of the packages, but makes it very difficult to figure out what changes are included in a specific version.

Risk
Low (doc-only).

Is this a regression from a previous update?

Root cause analysis:

Yes, this change split the description of nuget packages into "summary" and "description", but it looks like nuget.org only displays the description in such case.

How was the bug found?

I did a manual check while investigating another package documentation issue (#21574).

@jaredpar @dotnet/roslyn-infrastructure for review. Thanks

jcouv · 2017-09-18T16:10:29Z

ubuntu_14_debug_prtest failed with CURL error below (details).
FYI @dotnet/roslyn-infrastructure. I'll re-run.

08:59:47 dotnet-install: Downloading link: https://dotnetcli.azureedge.net/dotnet/Sdk/2.0.0-preview3-006923/dotnet-sdk-2.0.0-preview3-006923-linux-x64.tar.gz
08:59:47 
curl: (23) Failed writing body (4203 != 16383)
08:59:47 dotnet-install: Cannot download: https://dotnetcli.azureedge.net/dotnet/Sdk/2.0.0-preview3-006923/dotnet-sdk-2.0.0-preview3-006923-linux-x64.tar.gz
08:59:47 dotnet-install: Downloading legacy link: https://dotnetcli.azureedge.net/dotnet/Sdk/2.0.0-preview3-006923/dotnet-dev-ubuntu-x64.2.0.0-preview3-006923.tar.gz
08:59:47 curl: (22) The requested URL returned error: 404 Not Found

jcouv · 2017-09-18T16:10:37Z

test ubuntu_14_debug_prtest please

jcouv · 2017-09-18T16:43:06Z

ubuntu_14_debug_prtest failed again (details)

@dotnet/roslyn-infrastructure Is there a disc space issue on ubuntu machines?

09:11:14 FATAL: Could not checkout f3f33ee78c632965a5f77afd6d547f36068c661b
09:11:14 hudson.plugins.git.GitException: Could not checkout f3f33ee78c632965a5f77afd6d547f36068c661b
09:11:14 	at org.jenkinsci.plugins.gitclient.CliGitAPIImpl$9.execute(CliGitAPIImpl.java:2024)
09:11:14 	at org.jenkinsci.plugins.gitclient.RemoteGitImpl$CommandInvocationHandler$1.call(RemoteGitImpl.java:152)
09:11:14 	at org.jenkinsci.plugins.gitclient.RemoteGitImpl$CommandInvocationHandler$1.call(RemoteGitImpl.java:145)
09:11:14 	at hudson.remoting.UserRequest.perform(UserRequest.java:153)
09:11:14 	at hudson.remoting.UserRequest.perform(UserRequest.java:50)
09:11:14 	at hudson.remoting.Request$2.run(Request.java:332)
09:11:14 	at hudson.remoting.InterceptingExecutorService$1.call(InterceptingExecutorService.java:68)
09:11:14 	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
09:11:14 	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
09:11:14 	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
09:11:14 	at java.lang.Thread.run(Thread.java:748)
09:11:14 	at ......remote call to ubuntu1404-20170821-5c3f40(Native Method)
09:11:14 	at hudson.remoting.Channel.attachCallSiteStackTrace(Channel.java:1433)
09:11:14 	at hudson.remoting.UserResponse.retrieve(UserRequest.java:253)
09:11:14 	at hudson.remoting.Channel.call(Channel.java:797)
09:11:14 	at org.jenkinsci.plugins.gitclient.RemoteGitImpl$CommandInvocationHandler.execute(RemoteGitImpl.java:145)
09:11:14 	at sun.reflect.GeneratedMethodAccessor236.invoke(Unknown Source)
09:11:14 	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
09:11:14 	at java.lang.reflect.Method.invoke(Method.java:498)
09:11:14 	at org.jenkinsci.plugins.gitclient.RemoteGitImpl$CommandInvocationHandler.invoke(RemoteGitImpl.java:131)
09:11:14 	at com.sun.proxy.$Proxy166.execute(Unknown Source)
09:11:14 	at hudson.plugins.git.GitSCM.checkout(GitSCM.java:1120)
09:11:14 	at hudson.scm.SCM.checkout(SCM.java:495)
09:11:14 	at hudson.model.AbstractProject.checkout(AbstractProject.java:1278)
09:11:14 	at hudson.model.AbstractBuild$AbstractBuildExecution.defaultCheckout(AbstractBuild.java:604)
09:11:14 	at jenkins.scm.SCMCheckoutStrategy.checkout(SCMCheckoutStrategy.java:86)
09:11:14 	at hudson.model.AbstractBuild$AbstractBuildExecution.run(AbstractBuild.java:529)
09:11:14 	at hudson.model.Run.execute(Run.java:1720)
09:11:14 	at hudson.model.FreeStyleBuild.run(FreeStyleBuild.java:43)
09:11:14 	at hudson.model.ResourceController.execute(ResourceController.java:98)
09:11:14 	at hudson.model.Executor.run(Executor.java:404)
09:11:14 Caused by: hudson.plugins.git.GitException: Command "git checkout -f f3f33ee78c632965a5f77afd6d547f36068c661b" returned status code 128:
09:11:14 stdout: 
09:11:14 stderr: fatal: unable to write new index file

jcouv · 2017-09-19T18:24:39Z

test ubuntu_14_debug_prtest please

jcouv · 2017-09-19T19:48:09Z

test windows_determinism_prtest please

jcouv · 2017-09-19T19:49:18Z

test windows_debug_vs-integration_prtest please

jcouv · 2017-09-19T20:20:08Z

@jaredpar @dotnet/roslyn-infrastructure for review. This is fixing the description blurb for packages. Thanks

jaredpar · 2017-09-19T20:39:12Z

Also, I'm removing the summary section since it does not seem to appear anywhere.

CC @sharwell, @jasonmalinowski. Thought this appeared in the one line summary locations

jasonmalinowski

Indeed, summaries are shown in the NuGet package manager UI in Visual Studio, if not other places. Do not remove it.

jcouv · 2017-09-20T18:56:56Z

windows_debug_unit64_prtest failed with error below (details).
FYI @dotnet/roslyn-infrastructure I'll re-run.

CSC : error CS0016: Could not write to output file 'D:\j\workspace\windows_debug---f1572675\Binaries\Obj\TestUtilities\Debug\Roslyn.Test.Utilities.xml' -- 'The process cannot access the file 'D:\j\workspace\windows_debug---f1572675\Binaries\Obj\TestUtilities\Debug\Roslyn.Test.Utilities.xml' because it is being used by another process.' [D:\j\workspace\windows_debug---f1572675\src\Test\Utilities\Portable\TestUtilities.csproj]

jcouv · 2017-09-20T18:58:00Z

windows_determinism_prtest failed with a similar error (details)

CSC : error CS0016: Could not write to output file 'D:\j\workspace\windows_deter---bd1d49d3\Binaries\Obj\CSharpCompilerSymbolTest\Debug\Roslyn.Compilers.CSharp.Symbol.UnitTests.xml' -- 'The process cannot access the file 'D:\j\workspace\windows_deter---bd1d49d3\Binaries\Obj\CSharpCompilerSymbolTest\Debug\Roslyn.Compilers.CSharp.Symbol.UnitTests.xml' because it is being used by another process.' [D:\j\workspace\windows_deter---bd1d49d3\src\Compilers\CSharp\Test\Symbol\CSharpCompilerSymbolTest.csproj]

jcouv · 2017-09-20T18:58:09Z

test windows_debug_unit64_prtest please

jcouv · 2017-09-20T18:58:16Z

test windows_determinism_prtest please

jcouv · 2017-09-20T19:30:27Z

windows_debug_unit64_prtest failed again with a locked file (details).

@dotnet/roslyn-infrastructure Is this a known issue?

error CS0016: Could not write to output file 'D:\j\workspace\windows_debug---f1572675\Binaries\Obj\TestUtilities\Debug\Roslyn.Test.Utilities.xml' -- 'The process cannot access the file 'D:\j\workspace\windows_debug---f1572675\Binaries\Obj\TestUtilities\Debug\Roslyn.Test.Utilities.xml' because it is being used by another process.' [D:\j\workspace\windows_debug---f1572675\src\Test\Utilities\Portable\TestUtilities.csproj]

jasonmalinowski · 2017-09-20T19:31:38Z

My impression is @jaredpar and @nguerrera are investigating this right now. (Email also just sent internally.)

jcouv · 2017-09-21T17:02:27Z

@jasonmalinowski I added the summary blurbs back. Thanks for the feedback. Good to go?

jaredpar · 2017-09-19T20:37:37Z

src/NuGet/Microsoft.CodeAnalysis.CSharp.CodeStyle.nuspec

@@ -2,10 +2,13 @@
 <package xmlns="http://schemas.microsoft.com/packaging/2011/08/nuspec.xsd">
  <metadata minClientVersion="3.3">
    <id>Microsoft.CodeAnalysis.CSharp.CodeStyle</id>
-    <summary>


Think we still need a summary here

You may be looking at an older iteration. Latest commit is 4.

In reply to: 139810920 [](ancestors = 139810920)

jaredpar · 2017-09-19T20:37:46Z

src/NuGet/Microsoft.CodeAnalysis.CSharp.Features.nuspec

@@ -2,10 +2,13 @@
 <package xmlns="http://schemas.microsoft.com/packaging/2011/08/nuspec.xsd">
  <metadata minClientVersion="3.3">
    <id>Microsoft.CodeAnalysis.CSharp.Features</id>
-    <summary>
+    <description>


jasonmalinowski

Sorry a bunch of nitpicks on descriptions only because you chose to touch this. 😄 If you want to punt a few of these that's fine.

jasonmalinowski · 2017-09-21T17:39:56Z

src/NuGet/Microsoft.CodeAnalysis.Build.Tasks.nuspec

-        Contains the build task and targets used by MSBuild to run the C# and VB compilers.
-        Supports using VBCSCompiler on Windows.
+      The build task and targets used by MSBuild to run the C# and VB compilers.
+      Supports using VBCSCompiler on Windows.


I must admit I'm not sure how a customer will understand what VBCSCompiler is, much less how this package supports it on Windows.

I don't know either. I'll leave this one as-is.

jasonmalinowski · 2017-09-21T17:41:16Z

src/NuGet/Microsoft.CodeAnalysis.Compilers.nuspec

@@ -2,9 +2,13 @@
 <package xmlns="http://schemas.microsoft.com/packaging/2011/08/nuspec.xsd">
  <metadata minClientVersion="3.3">
    <id>Microsoft.CodeAnalysis.Compilers</id>
-    <summary>.NET Compiler Platform ("Roslyn")</summary>
+    <summary>
+      .NET Compiler Platform ("Roslyn").


Should this say it's the compiler layer? This otherwise sounds like it's the whole thing, which it's not.

jasonmalinowski · 2017-09-21T17:42:09Z

src/NuGet/Microsoft.CodeAnalysis.Compilers.nuspec

-      .NET Compiler Platform ("Roslyn"). Install this package to get both C# and Visual Basic support. Install either of the dependencies directly to get one of the languages separately.
+      .NET Compiler Platform ("Roslyn").
+      Install this package to get both C# and Visual Basic support.
+      Install either of the dependencies directly to get one of the languages separately.


This sentence is entirely correct and entirely impossible to read. "If you want just support for one language, install Microsoft.CodeAnalysis.CSharp or Microsoft.CodeAnalysis.VisualBasic".

jasonmalinowski · 2017-09-21T17:42:44Z

src/NuGet/Microsoft.CodeAnalysis.EditorFeatures.nuspec

@@ -6,9 +6,13 @@
      .NET Compiler Platform ("Roslyn") support for editor features inside the Visual Studio editor..
    </summary>
    <description>
+      .NET Compiler Platform ("Roslyn") support for editor features inside the Visual Studio editor..


Double period. Yes, you're just copying, but still...

jasonmalinowski · 2017-09-21T17:47:14Z

src/NuGet/Microsoft.Net.Compilers.nuspec

    </summary>
-    <description>$commitPathMessage$</description>
+    <description>
+      .Net Compilers package.


.NET is capitalized.

jasonmalinowski · 2017-09-21T17:48:14Z

src/NuGet/Microsoft.VisualStudio.LanguageServices.Razor.RemoteClient.nuspec

@@ -6,9 +6,13 @@
      .NET Compiler Platform ("Roslyn") support for Visual Studio "15".
    </summary>
    <description>
+      .NET Compiler Platform ("Roslyn") support for Visual Studio "15".


Uh, what should this one say? @heejaechang or @Pilchie?

* dotnet/master: (351 commits) Avoid scheduling an unnecessary dispose task for EmptyAsyncToken Support for ref-readonly locals (dotnet#22269) ported tests from dotnet#21263 (dotnet#22296) NormalizeWhitespace should not add a space in nullable type (dotnet#22234) Fix the work item number associated with the unit test Add unit test Terminate a sentence Add instructions for upgrading PowerShell Unsafe local should require /unsafe flag on compilation (dotnet#22268) CR feedback Not poisoning restricted types known to be stack only. Typo Error messsage should mention C# 7.0 not C# 7 (dotnet#22255) Package descriptions for CSharp and VB should include summary blurb (dotnet#22166) Fix a trivial issue in how IsLifted is calculated for C# compound assignment operator Do not zero out "With" statement target expression locals referenced within a lambda. (dotnet#22223) Fix unit test failure from merge Mark "private protected", "ref readonly" and other C# 7.2 features as merged (dotnet#22209) Add unit tests for IAwaitExpression and make the API public again more test fixes due to merge conflicts ...

* dotnet/master: (309 commits) Avoid scheduling an unnecessary dispose task for EmptyAsyncToken Support for ref-readonly locals (dotnet#22269) ported tests from dotnet#21263 (dotnet#22296) NormalizeWhitespace should not add a space in nullable type (dotnet#22234) Fix the work item number associated with the unit test Add unit test Terminate a sentence Add instructions for upgrading PowerShell Unsafe local should require /unsafe flag on compilation (dotnet#22268) CR feedback Not poisoning restricted types known to be stack only. Typo Error messsage should mention C# 7.0 not C# 7 (dotnet#22255) Package descriptions for CSharp and VB should include summary blurb (dotnet#22166) Fix a trivial issue in how IsLifted is calculated for C# compound assignment operator Do not zero out "With" statement target expression locals referenced within a lambda. (dotnet#22223) Fix unit test failure from merge Mark "private protected", "ref readonly" and other C# 7.2 features as merged (dotnet#22209) Add unit tests for IAwaitExpression and make the API public again more test fixes due to merge conflicts ...

Package descriptions for CSharp and VB should include summary blurb

efe1854

jcouv added Area-Compilers Area-Infrastructure labels Sep 18, 2017

jcouv added this to the 15.5 milestone Sep 18, 2017

jcouv self-assigned this Sep 18, 2017

jcouv requested a review from a team as a code owner September 18, 2017 15:59

dnfclas added the cla-already-signed label Sep 18, 2017

jcouv added the Blocked label Sep 18, 2017

jasonmalinowski requested changes Sep 20, 2017

View reviewed changes

jcouv added 3 commits September 20, 2017 10:47

Putting summaries back in

22c1730

Shortening summaries as they used to be

2818c17

Tweak

04111c2

jcouv removed the Blocked label Sep 20, 2017

jaredpar approved these changes Sep 21, 2017

View reviewed changes

jasonmalinowski approved these changes Sep 21, 2017

View reviewed changes

Tweaks from Jason

bb6ec80

jcouv merged commit 633f8b2 into dotnet:master Sep 21, 2017

jcouv deleted the package-description branch September 21, 2017 20:14

jcouv mentioned this pull request Oct 22, 2017

Where are the release notes or changelog? #18333

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Package descriptions for CSharp and VB should include summary blurb #22166

Package descriptions for CSharp and VB should include summary blurb #22166

jcouv commented Sep 18, 2017

jcouv commented Sep 18, 2017

jcouv commented Sep 18, 2017

jcouv commented Sep 18, 2017

jcouv commented Sep 19, 2017

jcouv commented Sep 19, 2017

jcouv commented Sep 19, 2017

jcouv commented Sep 19, 2017

jaredpar commented Sep 19, 2017

jasonmalinowski left a comment

jcouv commented Sep 20, 2017

jcouv commented Sep 20, 2017

jcouv commented Sep 20, 2017

jcouv commented Sep 20, 2017

jcouv commented Sep 20, 2017

jasonmalinowski commented Sep 20, 2017

jcouv commented Sep 21, 2017

jaredpar Sep 19, 2017

jcouv Sep 21, 2017

jaredpar Sep 19, 2017

jasonmalinowski left a comment

jasonmalinowski Sep 21, 2017

jcouv Sep 21, 2017

jasonmalinowski Sep 21, 2017

jasonmalinowski Sep 21, 2017

jasonmalinowski Sep 21, 2017

jasonmalinowski Sep 21, 2017

jasonmalinowski Sep 21, 2017

Package descriptions for CSharp and VB should include summary blurb #22166

Package descriptions for CSharp and VB should include summary blurb #22166

Conversation

jcouv commented Sep 18, 2017

jcouv commented Sep 18, 2017

jcouv commented Sep 18, 2017

jcouv commented Sep 18, 2017

jcouv commented Sep 19, 2017

jcouv commented Sep 19, 2017

jcouv commented Sep 19, 2017

jcouv commented Sep 19, 2017

jaredpar commented Sep 19, 2017

jasonmalinowski left a comment

Choose a reason for hiding this comment

jcouv commented Sep 20, 2017

jcouv commented Sep 20, 2017

jcouv commented Sep 20, 2017

jcouv commented Sep 20, 2017

jcouv commented Sep 20, 2017

jasonmalinowski commented Sep 20, 2017

jcouv commented Sep 21, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasonmalinowski left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment