Merge pull request #107 from cake-contrib/feature/GH-80

(GH-80) existing icons will be honored

Author: nils-a

.github/workflows/build.yml

@@ -13,10 +13,10 @@ jobs:
     if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != github.repository
     strategy:
       matrix:
-        os: [windows-latest, ubuntu-latest, macos-latest]
+        os:  [ ubuntu-18.04, windows-2019, macos-10.15 ]
 
     steps:
-      - uses: actions/checkout@v2.3.4
+      - uses: actions/checkout@v2
         with:
           fetch-depth: 0
           ref: ${{ github.event.ref }}
@@ -31,7 +31,7 @@ jobs:
           script-path: recipe.cake
           target: CI
           verbosity: Diagnostic
-          cake-version: 0.38.4
+          cake-version: 0.38.5
           cake-bootstrap: true
       # currently, Cake.Recipe does not upload artifacts when run on gh-actions
       - name: Upload Issues
@@ -44,7 +44,7 @@ jobs:
             BuildArtifacts/**/coverlet/*.xml
       - name: Upload Packages
         uses: actions/upload-artifact@v2
-        if: matrix.os == 'windows-latest'
+        if: runner.os == 'Windows'
         with:
           if-no-files-found: warn
           name: package

.github/workflows/codeql-analysis.yml

@@ -17,7 +17,7 @@ on:
 jobs:
   analyze:
     name: Analyze
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-18.04
 
     strategy:
       fail-fast: false
@@ -30,7 +30,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v2.3.4
+      uses: actions/checkout@v2
       with:
         fetch-depth: 0
 
@@ -49,7 +49,7 @@ jobs:
         # Prefix the list here with "+" to use these queries and those in the config file.
         # queries: ./path/to/local/query, your-org/your-repo/queries@main
 
-    - run: ./build.ps1
+    - run: ./build.ps1 --target=DotNetCore-Build
       shell: pwsh
 
     - name: Perform CodeQL Analysis

.github/workflows/publishDocs.yml

@@ -15,7 +15,7 @@ jobs:
 
     steps:
     - name: checkout
-      uses: actions/checkout@v2.3.4 #https://github.com/actions/checkout
+      uses: actions/checkout@v2
       with:
         fetch-depth: 0 # GitVersion is somewhat irritated when fetch-depth is "1"....
         ref: ${{ github.event.ref }}

.github/workflows/updateToc.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2.3.4
+      - uses: actions/checkout@v2
         with:
           fetch-depth: 0
           ref: ${{ github.event.ref }}

build.sh

@@ -11,7 +11,6 @@ Title: CakeContrib-Icon
 - [Related rules](#related-rules)
 - [Usage](#usage)
 - [Settings](#settings)
-  - [Icon-Location](#icon-location)
   - [Icon include in project](#icon-include-in-project)
 - [Migrating from an existing project](#migrating-from-an-existing-project)
 
@@ -34,21 +33,22 @@ Title: CakeContrib-Icon
 Using this package automatically enables this guideline.
 
 With no special settings at all (i.e. "The Standard"):
-* the current cake-contrib icon will be copied as "icon.png" in the project-directory 
-* the icon will be included in the project
+* if no `PackageIcon` property is specified, a default will be assigned.
+* if no icon (matching the `PackageIcon` property) is referenced in the project, a default will be referenced.
+* if the referenced icon is not binary equal to the default icon, it will be updated.
+* if no `PackageIconUrl` property is specified, a default will be assigned.
 
 ## Settings
 
-### Icon-Location
-<?! Include "../settings/fragments/IconDestinationLocation.md" /?>
-
 ### Icon include in project
 <?! Include "../settings/fragments/IconOmitImport.md" /?>
 
 ## Migrating from an existing project
 
+No steps are needed anymore. Existing settings will be detected and honored.
+
+Optionally:
 * remove the existing icon
 * remove the `Include` of the icon from the project-file
-* add a reference to CakeContrib.Guidelines
-* build the project
-* set `PackageIcon` to `icon.png`
+* remove the `PackageIcon` from the project-file
+* remove the `PackageIconUrl` from the project-file

docs/input/guidelines/CakeContribIcon.md

@@ -28,15 +28,9 @@ To that end, setting `PackageIcon` is required.
 
 ## How to fix violations
 
-Add 
+This error will only show, if `CakeContribGuidelinesIconOmitImport` is `True` and no manual include of the icon was done.
 
-```xml
-<PropertyGroup>
-    <PackageIcon>$(CakeContribGuidelinesIconDestinationLocation)</PackageIcon>
-</PropertyGroup>
-```
-
-to the project.
+To fix this error, you need to remove the definition of `CakeContribGuidelinesIconOmitImport` or define a `PackageIcon` manually.
 
 ## Related guidelines
 

docs/input/rules/ccg0001.md

@@ -1,10 +1,10 @@
 ---
 Order: 3
 Title: CCG0003
-Description:  PackageIcon points to wrong place
+Description:  PackageIcon can not be updated
 ---
 
- > PackageIcon points to wrong place
+ > The PackageIcon source (path/to/icon.jpeg) has an extension of jpeg. It can not be set from the CakeContrib-Icon.
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -19,16 +19,27 @@ Description:  PackageIcon points to wrong place
 
 ## Cause
 
-This warning is raised, when `PackageIcon` does not point to the copied icon. 
-(I.e. `PackageIcon` is not equal to `$(CakeContribGuidelinesIconDestinationLocation)`)
+This warning/error is raised, when the source of `PackageIcon` was outdated 
+but could not be updated. 
 
 ## Description
 
-Since the correct icon is copied to `$(CakeContribGuidelinesIconDestinationLocation)` it is expected, that this icon is packaged into the nupkg.
+The default package icon is a `png` and will be used to update outdated icons.
+If a different icon format than `png` is used, simply updating that icon with a
+`png` content will break the icon.
+
+If a `PackageIcon` is set, but no corresponding icon reference could be
+found, a reference should be added automatically. However, if `PackageIcon`
+is not set to a `png` file, such reference would not be possible.
+In this case `CCG0003` is an error and will break the build.
+
+If a `PackageIcon` is set with a corresponding icon reference but not to
+a `png` file, a test whether the icon is up-to-date is not possible.
+In this case `CCG0003` is a warning .
 
 ## How to fix violations
 
-Modify `PackageIcon` to point to the same place as `$(CakeContribGuidelinesIconDestinationLocation)`.
+Modify `PackageIcon` to point to a `png` file or remove the custom file entirely.
 
 ## Related guidelines
 

docs/input/rules/ccg0003.md

@@ -5,18 +5,17 @@
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-The cake-contrib icon will be automatically included in the project, unless `CakeContribGuidelinesIconOmitImport` was defined.
+The cake-contrib icon will be automatically included in the project, unless 
+`CakeContribGuidelinesIconOmitImport` is set to `True`.
 
 To to use a "custom" import the following could be used:
 
 ```xml
 <PropertyGroup>
-    <CakeContribGuidelinesIconOmitImport>1</CakeContribGuidelinesIconOmitImport>
+    <CakeContribGuidelinesIconOmitImport>True</CakeContribGuidelinesIconOmitImport>
+    <PackageIcon>logo.png</PackageIcon>
 </PropertyGroup>
 <ItemGroup>
-    <None Include="$(CakeContribGuidelinesIconDestinationLocation)">
-        <Pack>True</Pack>
-        <PackagePath></PackagePath>
-    </None>
+    <None Include="icons/logo.png" Pack="True" PackagePath="" />
 </ItemGroup> 
 ```