ADD: ReleaseAssetList module

CHANGELOG.md

@@ -10,6 +10,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### New features
 
 - A new property `CompletePublishFolderMetadataDependsOn` has been added. The `CompletePublishFolderMetadata` target will depend on targets listed in this property. This is useful to separate concerns among alternate pack methods.
+- The new `ReleaseAssetList` module allows for creation of lists of assets to associate with a release, useful when releases are created externally (GitHub, etc.) and associated assets are the only way to retrieve published artifacts.
+  - release asset list generation is enabled by the `GenerateReleaseAssetList` boolean property, defaulting to `true` except in libraries and test projects;
+  - to include a file in the release asset list for a project, just add one or more `ReleaseAsset` items;
+  - the `Description` metadata of `ReleaseAsset` items can be used to add a textual description of each asset, for CI systems that can use it;
+  - release assets without a `Description` metadata are given a default description according to the `DefaultReleaseAssetDescription` property, whose default value is "(no description given)";
+  - release asset lists are UTF-8 text files;
+    - each row of a release asset list contains the full path of an asset, a tab character (Unicode U+0009), and the asset's description;
+    - rows are separated by the build system's line separator (CR+LF on Windows, LF otherwise);
+  - each project in a solution generates its own release asset list, whose name can be set via the `ReleaseAssetListFileName` property, defaulting to `$(MSBuildProjectName).assets.txt`;
+  - all release asset lists for a solution are placed in the artifacts directory, `$(ArtifactsDirectory)$(Configuration)`.
 - New metadata in `PublishFolder` items allow for zipping a published folder:
   - `CreateZipFile` (boolean) enables the creation of a ZIP file with the contents of the published folder;
   - `ZipFileName` (string) is the name (complete with extension) of the created ZIP file;
@@ -21,7 +31,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - `$(MSBuildProjectName)-%(PublishFolder.Identity)_$(BuildVersion).zip` if the `BuildVersion` property is set (such as when using Nerdbank.GitVersioning);
     - `$(MSBuildProjectName)-%(PublishFolder.Identity).zip` otherwise.
 
-
 ### Changes to existing features
 
 - The minimum supported version of Roslyn is now 4.7

docs/Diagnostics.md

@@ -12,6 +12,7 @@
 - [XmlDocumentation module (1800-1899)](#xmldocumentation-module-1800-1899)
 - [AlternatePack module (1900-1999)](#alternatepack-module-1900-1999)
 - [NerdbankGitVersioning module (2000-2099)](#nerdbankgitversioning-module-2000-2099)
+- [ReleaseAssetList module (2100-2199)](#releaseassetlist-module-2100-2199)
 
 ## Overview
 
@@ -100,3 +101,9 @@ Each module is assigned a contiguous range of 100 diagnostics, as listed below.
 | Code | Severity | Message | Description |
 | -----| :------: | ------- | ----------- |
 | BVSDK2000 | Error | Version specification JSON file not found. | A `version.json` or `.version.json` file for the project was not found within the repository root. |
+
+## ReleaseAssetList module (2100-2199)
+
+| Code | Severity | Message | Description |
+| -----| :------: | ------- | ----------- |
+| This module has no associated diagnostics. |  |  |  |

src/Buildvana.Sdk/Modules/ReleaseAssetList/Module.Core.targets

@@ -0,0 +1,50 @@
+<Project>
+
+  <Target Name="PrepareReleaseAssetList"
+          AfterTargets="Pack"
+          DependsOnTargets="$(WriteReleaseAssetListDependsOn)"
+          Condition="$(GenerateReleaseAssetList)">
+
+    <PropertyGroup Condition="'$(ReleaseAssetDefaultDescription)' == ''">
+      <ReleaseAssetDefaultDescription>(no description given)</ReleaseAssetDefaultDescription>
+    </PropertyGroup>
+
+    <ItemGroup>
+      <ReleaseAsset Update="%(ReleaseAsset.Identity)"
+                    Description="$([System.String]::Copy('%(ReleaseAsset.Description)').Trim())" />
+      <ReleaseAsset Update="%(ReleaseAsset.Identity)"
+                    Condition="'%(ReleaseAsset.Description)' == ''"
+                    Description="$(ReleaseAssetDefaultDescription)" />
+    </ItemGroup>
+
+  </Target>
+
+  <Target Name="WriteReleaseAssetList"
+          AfterTargets="Pack"
+          DependsOnTargets="$(WriteReleaseAssetListDependsOn);PrepareReleaseAssetList"
+          Condition="$(GenerateReleaseAssetList)">
+
+    <ItemGroup>
+      <BV_ReleaseAssetText Include="%(ReleaseAsset.FullPath)&#09;%(Description)" />
+    </ItemGroup>
+
+    <PropertyGroup>
+      <ReleaseAssetListFileName Condition="'$(ReleaseAssetListFileName)' == ''">$(MSBuildProjectName).assets.txt</ReleaseAssetListFileName>
+      <ReleaseAssetListPath Condition="'$(ReleaseAssetListPath)' == ''">$(ArtifactsDirectory)$(Configuration)\$(ReleaseAssetListFileName)</ReleaseAssetListPath>
+    </PropertyGroup>
+
+    <WriteLinesToFile Condition="@(ReleaseAsset->Count()) > 0"
+                      File="$(ReleaseAssetListPath)"
+                      Lines="@(BV_ReleaseAssetText)"
+                      Overwrite="true" />
+
+    <Delete Condition="@(ReleaseAsset->Count()) == 0"
+            Files="$(ReleaseAssetListPath)" />
+
+    <ItemGroup>
+      <BV_ReleaseAssetText Remove="@(BV_ReleaseAssetText)" />
+    </ItemGroup>
+
+  </Target>
+
+</Project>

src/Buildvana.Sdk/Modules/ReleaseAssetList/Module.targets

@@ -0,0 +1,17 @@
+<Project>
+
+  <!-- The default for GenerateReleaseAssetList is true, except for libraries and test projects -->
+  <PropertyGroup Condition="'$(GenerateReleaseAssetList)' == ''">
+    <GenerateReleaseAssetList>true</GenerateReleaseAssetList>
+    <GenerateReleaseAssetList Condition="$(BV_IsLibraryProject) Or $(BV_IsTestProject)">false</GenerateReleaseAssetList>
+  </PropertyGroup>
+
+  <!-- Coalesce GenerateReleaseAssetList to a boolean value, defaulting to false -->
+  <PropertyGroup Condition="'$(GenerateReleaseAssetList)' != 'true'">
+    <GenerateReleaseAssetList>false</GenerateReleaseAssetList>
+  </PropertyGroup>
+
+  <Import Project="Module.Core.targets"
+          Condition="$(GenerateReleaseAssetList)" />
+
+</Project>