Skip to content

GH3517: Add NuGet Pack ReadMe Support #3518

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

Closed
devlead wants to merge 1 commit into from
Closed

GH3517: Add NuGet Pack ReadMe Support #3518

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
27 changes: 27 additions & 0 deletions src/Cake.Common.Tests/Properties/Resources.Designer.cs
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

21 changes: 21 additions & 0 deletions src/Cake.Common.Tests/Properties/Resources.resx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1370,6 +1370,27 @@ Line #3]]></releaseNotes>
<file src="Cake.Core.pdb" target="lib/net45" />
<file src="LICENSE" />
</files>
&lt;/package&gt;</value>
</data>
<data name="Nuspec_ReadMe" xml:space="preserve">
<value>&lt;?xml version=&quot;1.0&quot; encoding=&quot;utf-8&quot;?&gt;
&lt;package xmlns:xsi=&quot;http://www.w3.org/2001/XMLSchema-instance&quot; xmlns:xsd=&quot;http://www.w3.org/2001/XMLSchema&quot;&gt;
&lt;metadata xmlns=&quot;http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd&quot;&gt;
&lt;id&gt;TheID&lt;/id&gt;
&lt;version&gt;1.0.0&lt;/version&gt;
&lt;title&gt;The Title&lt;/title&gt;
&lt;authors&gt;Author #1,Author #2&lt;/authors&gt;
&lt;owners&gt;Owner #1,Owner #2&lt;/owners&gt;
&lt;description&gt;The Description&lt;/description&gt;
&lt;readme&gt;docs\NuGet.org.md&lt;/readme&gt;
&lt;/metadata&gt;
&lt;files&gt;
&lt;file src=&quot;Cake.Core.dll&quot; target=&quot;lib/net45&quot; /&gt;
&lt;file src=&quot;Cake.Core.xml&quot; target=&quot;lib/net45&quot; /&gt;
&lt;file src=&quot;Cake.Core.pdb&quot; target=&quot;lib/net45&quot; /&gt;
&lt;file src=&quot;LICENSE&quot; /&gt;
&lt;file src=&quot;../nuspec/NuGet.org.md&quot; target=&quot;docs&quot; /&gt;
&lt;/files&gt;
&lt;/package&gt;</value>
</data>
<data name="TeamCity_Config_Properties_Xml" xml:space="preserve">
Expand Down
24 changes: 24 additions & 0 deletions src/Cake.Common.Tests/Unit/Tools/NuGet/Pack/NuGetPackerTests.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -899,6 +899,30 @@ public void Should_Replace_Template_Tokens_In_Nuspec_With_Files_And_DependencyTa
Resources.Nuspec_Metadata_WithoutNamespaces_WithTargetFramworkDependencies.NormalizeLineEndings(),
result.NuspecContent.NormalizeLineEndings());
}

[Fact]
public void Should_Add_ReadMe_Element_To_Nuspec_If_Missing()
{
// Given
var fixture = new NuGetPackerWithNuSpecFixture();
fixture.WithNuSpecXml(Resources.Nuspec_NoMetadataElement);

fixture.Settings.Id = "TheID";
fixture.Settings.Version = "1.0.0";
fixture.Settings.Title = "The Title";
fixture.Settings.Authors = new[] { "Author #1", "Author #2" };
fixture.Settings.Owners = new[] { "Owner #1", "Owner #2" };
fixture.Settings.Description = "The Description";
fixture.Settings.ReadMePath = "../nuspec/NuGet.org.md";

// When
var result = fixture.Run();

// Then
Assert.Equal(
Resources.Nuspec_ReadMe.NormalizeLineEndings(),
result.NuspecContent.NormalizeLineEndings());
}
}

public sealed class WithProjectFile
Expand Down
6 changes: 6 additions & 0 deletions src/Cake.Common/Tools/NuGet/Pack/NuGetPackSettings.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -272,5 +272,11 @@ public sealed class NuGetPackSettings : ToolSettings
/// <c>true</c> if the output should be placed in the tool folder inside the NuGet package; otherwise <c>false</c>.
/// </value>
public bool OutputToToolFolder { get; set; }

/// <summary>
/// Gets or sets Path to markdown Markdown (.md) file containing package readme packed into docs folder.

@augustoproiete augustoproiete Oct 5, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
/// Gets or sets Path to markdown Markdown (.md) file containing package readme packed into docs folder.
/// Gets or sets Path to markdown Markdown (.md) file containing package readme.

AFAIK there's no requirement for the README to be in a docs folder - it can be anywhere in the package. Most of the examples I see have the README.md file at the root of the package

/// </summary>
/// <value>The readme path.</value>
public FilePath ReadMePath { get; set; }
}
}
36 changes: 26 additions & 10 deletions src/Cake.Common/Tools/NuGet/Pack/NuspecTransformer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,8 @@ private static IDictionary<string, Func<NuGetPackSettings, string>> CreateMappin
{ "copyright", x => ToString(settings.Copyright) },
{ "language", x => ToString(settings.Language) },
{ "tags", x => ToSpaceSeparatedString(settings.Tags) },
{ "serviceable", x => ToString(settings.Serviceable) }
{ "serviceable", x => ToString(settings.Serviceable) },
{ "readme", x => settings.ReadMePath is { } readme ? string.Concat("docs\\", readme.GetFilename().FullPath) : null },

@augustoproiete augustoproiete Oct 5, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
{ "readme", x => settings.ReadMePath is { } readme ? string.Concat("docs\\", readme.GetFilename().FullPath) : null },
{ "readme", x => settings.ReadMePath is { } readme ? readme.GetFilename().FullPath : null },

Same as above: AFAIK there's no requirement for the README to be in a docs folder - it can be anywhere in the package. Most of the examples I see have the README.md file at the root of the package

};
}

Expand Down Expand Up @@ -108,17 +109,25 @@ private static void AddComplexTypesToXmlDocument(XmlDocument document, NuGetPack
private static void CreateFileElements(XmlDocument document, NuGetPackSettings settings,
XmlNamespaceManager namespaceManager)
{
if (settings.Files != null && settings.Files.Count > 0)
var hasFiles = settings.Files != null && settings.Files.Count > 0;
var hasReadMe = settings.ReadMePath != null;

if (!hasFiles && !hasReadMe)
{
var filesPath = string.Format(CultureInfo.InvariantCulture,
"//*[local-name()='package']/*[local-name()='files']");
var filesElement = document.SelectSingleNode(filesPath, namespaceManager);
if (filesElement == null)
{
var package = GetPackageElement(document);
filesElement = document.CreateAndAppendElement(package, "files");
}
return;
}

var filesPath = string.Format(CultureInfo.InvariantCulture,
"//*[local-name()='package']/*[local-name()='files']");
var filesElement = document.SelectSingleNode(filesPath, namespaceManager);
if (filesElement == null)
{
var package = GetPackageElement(document);
filesElement = document.CreateAndAppendElement(package, "files");
}

if (hasFiles)
{
filesElement.RemoveAll();
foreach (var file in settings.Files)
{
Expand All @@ -131,6 +140,13 @@ private static void CreateFileElements(XmlDocument document, NuGetPackSettings s
}
}
}

if (hasReadMe)
{
var fileElement = document.CreateAndAppendElement(filesElement, "file");

@augustoproiete augustoproiete Oct 5, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I haven't actually run this to test, but I'm under the impression the README could already be present in the list of files - wouldn't this duplicate the entry in the nuspec?

fileElement.AddAttributeIfSpecified(settings.ReadMePath.FullPath, "src");
fileElement.AddAttributeIfSpecified("docs", "target");

@augustoproiete augustoproiete Oct 5, 2021

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Same as above: AFAIK there's no requirement for the README to be in a docs folder - it can be anywhere in the package. Most of the examples I see have the README.md file at the root of the package

}
}

private static void CreateContentFileElements(XmlDocument document, NuGetPackSettings settings,
Expand Down