add plugin reference

add site generation to release build

README.md

@@ -104,7 +104,7 @@ can be overridden with the `<localMavenNugetRepositoryName>` and `<localMavenNug
 
 ## build
 
-The `build` goal is bound to the `compile` phase. It will call `dotnet build` on the current project. Be that a .sln 
+The `build` goal is bound to the `compile` phase. It will call `dotnet build` on the current project, be that a .sln 
 or .csproj file. It will always add the command line option `-p:Version=<projectVersion>` with `projectVersion` being 
 the goals parameter of the same name. This way the version of the build artifacts are managed in the pom.
 
@@ -143,4 +143,9 @@ custom `clean` goal is called, which simply calls `dotnet clean`
 
 # examples
 
-Examples can be found with the [integration tests](src/it)
+Examples can be found with the [integration tests](src/it)
+
+# opt out
+
+When calling `dotnet` this plugin will always set the environment variable `DOTNET_CLI_TELEMETRY_OPTOUT` to `TRUE` if 
+not overwritten by the `environmentVariables` parameter.

pom.xml

@@ -3,9 +3,9 @@
     <modelVersion>4.0.0</modelVersion>
 
     <parent>
-        <groupId>de.eitco</groupId>
+        <groupId>de.eitco.cicd</groupId>
         <artifactId>eitco-oss-parent</artifactId>
-        <version>0.0.14</version>
+        <version>0.0.15</version>
     </parent>
 
 
@@ -31,6 +31,7 @@
         <developerConnection>scm:git:https://github.com/eitco/dotnet-maven-plugin.git</developerConnection>
         <tag>HEAD</tag>
     </scm>
+
     <properties>
         <maven-clean-plugin.version>3.3.2</maven-clean-plugin.version>
     </properties>
@@ -74,23 +75,46 @@
         <plugins>
             <plugin>
                 <artifactId>maven-release-plugin</artifactId>
+                <configuration>
+                    <goals>deploy site site:stage scm-publish:publish-scm</goals>
+                </configuration>
             </plugin>
             <plugin>
                 <artifactId>maven-resources-plugin</artifactId>
             </plugin>
             <plugin>
                 <artifactId>maven-invoker-plugin</artifactId>
-                <configuration>
-<!--                    <debug>true</debug>-->
-                    <showErrors>true</showErrors>
-                    <streamLogsOnFailures>true</streamLogsOnFailures>
-                </configuration>
             </plugin>
             <plugin>
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>license-maven-plugin</artifactId>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-site-plugin</artifactId>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-scm-publish-plugin</artifactId>
+            </plugin>
         </plugins>
     </build>
 
+    <reporting>
+        <excludeDefaults>true</excludeDefaults>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-plugin-report-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </reporting>
+
+    <distributionManagement>
+        <site>
+            <id>github</id>
+            <url>scm:git:https://github.com/eitco/eitco.github.io.git</url>
+        </site>
+    </distributionManagement>
+
 </project>

src/main/java/de/eitco/cicd/dotnet/AbstractDotnetMojo.java

@@ -16,36 +16,63 @@
 
 public abstract class AbstractDotnetMojo extends AbstractMojo {
 
+    /**
+     * This parameter specifies the directory where to execute {@code dotnet} and thus where the
+     * project files are located
+     */
     @Parameter(defaultValue = "${project.basedir}")
     protected File workingDirectory;
 
+    /**
+     * This parameter specifies the location of the {@code dotnet} executable. If not set {@code dotnet} being
+     * available by the {@code PATH} environment variable is assumed.
+     */
     @Parameter
     protected File dotnetExecutable;
 
+    /**
+     * This parameter specifies the directory where {@code dotnet} writes its generated package(s) to.
+     */
     @Parameter(defaultValue = "${project.build.directory}/dotnet")
     protected File targetDirectory;
 
+    /**
+     * This parameter specifies the version of this project given to {@code dotnet} by the {@code -p:Version=}
+     * command line parameter.
+     */
     @Parameter(defaultValue = "${project.version}")
     protected String projectVersion;
 
+    /**
+     * This parameter specifies the assembly version of this project. Keep in mind that the assembly version needs to
+     * consist of up to 4 numeric values separated by '.' e.g.: {@code <major>.<minor>.<patch>.<build>}.
+     */
     @Parameter
     protected String assemblyVersion;
 
+    /**
+     * This parameter specifies the {@code Company} added to the compiles executables or libraries.
+     */
     @Parameter(defaultValue = "${project.organization.name}")
     protected String vendor;
 
+    /**
+     * This parameter specifies nuget sources to be added to the project. These are the locations where {@code nuget}
+     * will read dependencies from. The value of each entry is the url of the remote repository. The key is a unique
+     * name {@code nuget} will use to identify the repository by. It can also be used to add
+     * <a href="https://maven.apache.org/settings.html#servers">credentials</a> to using {@code <server>}
+     * elements in the {@code settings.xml}.
+     *
+     * Consider to <a href="https://maven.apache.org/guides/mini/guide-encryption.html">encrypt passwords</a> in
+     * your {@code settings.xml}
+     *
+     * Note that crendentials added this way will be written to your nuget configuration file. On windows systems
+     * the credentials will be encrypted, however on linux systems password encryption is not supported by
+     * {@code nuget} - so the credentials will be written to the {code nuget} config way unencrypted.
+     */
     @Parameter
     protected Map<String, String> nugetSources = Map.of();
 
-    @Parameter(defaultValue = "${settings}", readonly = true)
-    protected Settings settings;
-
-    @Parameter(defaultValue = "maven-nuget-local")
-    protected String localMavenNugetRepositoryName;
-
-    @Parameter(defaultValue = "${settings.localRepository}")
-    protected String localMavenNugetRepositoryBaseDirectory;
-
     /**
      * This parameter specifies custom properties given to dotnet via '-p:'. Keep in mind that the 'Version', 'Company',
      * 'Description', 'RepositoryUrl' and 'AssemblyVersion' properties will be overwritten by their respective
@@ -54,9 +81,36 @@ public abstract class AbstractDotnetMojo extends AbstractMojo {
     @Parameter
     protected Map<String, String> customProperties = Map.of();
 
+    /**
+     * This parameter specifies additional environment variables to be added to the {@code dotnet} process.
+     * <br/>
+     * Note that the {@code DOTNET_CLI_TELEMETRY_OPTOUT} will be set to {@code TRUE} if not overwritten with
+     * this parameter.
+     */
     @Parameter
     protected Map<String, String> environmentVariables = Map.of();
 
+    /**
+     * This parameter specifies the symbolic name of the local nuget repository. The local nuget repository is a
+     * special file system repository this plugin copies the generated packages in the {@code install} phase to.
+     * This simulates mavens local repository.
+     * <br/>
+     * The location of the local nuget repository can be configured by {@link #localMavenNugetRepositoryBaseDirectory}.
+     */
+    @Parameter(defaultValue = "maven-nuget-local")
+    protected String localMavenNugetRepositoryName;
+
+    /**
+     * This parameter specifies the location of the local nuget repository. The local nuget repository is a
+     * special file system repository this plugin copies the generated packages in the {@code install} phase to.
+     * This simulates mavens local repository.
+     */
+    @Parameter(defaultValue = "${settings.localRepository}")
+    protected String localMavenNugetRepositoryBaseDirectory;
+
+    @Parameter(defaultValue = "${settings}", readonly = true)
+    protected Settings settings;
+
     @Component(hint = "dotnet-security")
     private SecDispatcher securityDispatcher;
 

src/main/java/de/eitco/cicd/dotnet/BuildMojo.java

@@ -6,9 +6,19 @@
 import org.apache.maven.plugins.annotations.Parameter;
 
 
+/**
+ * This goal calls `dotnet build` on the current project, be that a {@code .sln}
+ * or {@code .csproj} file. It will always add the command line option {@code -p:Version=<projectVersion>} with
+ * {@code projectVersion} being the goals parameter of the same name. This way the version of the build artifacts
+ * are managed in the pom.
+ */
 @Mojo(name = "build", defaultPhase = LifecyclePhase.COMPILE)
 public class BuildMojo extends AbstractDotnetMojo {
 
+    /**
+     * This parameter specifies which configuration will be built. Normally, at least {@code RELEASE}
+     * and {@code DEBUG} are available.
+     */
     @Parameter
     private String configurationName;
 

src/main/java/de/eitco/cicd/dotnet/CleanMojo.java

@@ -4,6 +4,9 @@
 import org.apache.maven.plugins.annotations.LifecyclePhase;
 import org.apache.maven.plugins.annotations.Mojo;
 
+/**
+ * This goal simply calls {@code dotnet clean}.
+ */
 @Mojo(name = "clean", defaultPhase = LifecyclePhase.CLEAN)
 public class CleanMojo extends AbstractDotnetMojo {
 

src/main/java/de/eitco/cicd/dotnet/InitializeMojo.java

@@ -8,6 +8,10 @@
 import java.io.File;
 import java.util.Map;
 
+/**
+ * This goal registers nuget source repositories. A special one that helps mimic mavens local repository
+ * and additionally all repositories that are configured.
+ */
 @Mojo(name = "initialize", defaultPhase = LifecyclePhase.INITIALIZE)
 public class InitializeMojo extends AbstractDotnetMojo {
 

src/main/java/de/eitco/cicd/dotnet/InstallMojo.java

@@ -10,10 +10,16 @@
 import java.nio.file.Files;
 import java.nio.file.StandardCopyOption;
 
+/**
+ * This goal assumes the builds delivery artifacts to be located in the directory denoted by the goals
+ * `targetDirectory` parameter. It will simply copy all *.nupkg files located there to directory configured
+ * to be the local nuget directory.
+ */
 @Mojo(name = "install", defaultPhase = LifecyclePhase.INSTALL)
 public class InstallMojo extends AbstractDotnetMojo {
 
     public static final String NUPKG_SUFFIX = ".nupkg";
+
     private static File globalsCacheDirectory;
 
     @Override

src/main/java/de/eitco/cicd/dotnet/NugetPushMojo.java

@@ -7,26 +7,50 @@
 import org.apache.maven.project.MavenProject;
 import org.apache.maven.settings.Server;
 
+/**
+ * This goal calls {@code nuget push} on every nupgk file located in the configured
+ * {@code targetDirectory}.
+ */
 @Mojo(name = "push", defaultPhase = LifecyclePhase.DEPLOY)
 public class NugetPushMojo extends AbstractDotnetMojo {
 
+    /**
+     * This parameter specifies the id of the nuget server to push to. This id is used to find the
+     * corresponding {@code <server>} entry in the {@code settings.xml} for authentication.
+     */
     @Parameter(defaultValue = "nuget-server")
     protected String nugetServerId;
+
+    /**
+     * This parameter specifies the url of the nuget server to push to.
+     */
     @Parameter
     private String nugetServerUrl;
 
+    /**
+     * This parameter specifies an alternative url of a server to push to which is only used
+     * if the current version is a snapshot version.
+     */
     @Parameter
     private String nugetSnapshotServerUrl;
 
-    @Parameter(defaultValue = "${project}", readonly = true)
-    protected MavenProject project;
-
+    /**
+     * If set to {@code true} this parameter forces the configured target server to be added as
+     * a nuget source.
+     */
     @Parameter
     private Boolean forceAddSource;
 
+    /**
+     * This parameter specifies the repository name that is used when added as nuget source. If
+     * it is not specified it defaults to {@link #nugetServerId}.
+     */
     @Parameter
     private String repositoryName;
 
+    @Parameter(defaultValue = "${project}", readonly = true)
+    protected MavenProject project;
+
     @Override
     public void execute() throws MojoExecutionException {
 

src/main/java/de/eitco/cicd/dotnet/PackMojo.java

@@ -6,12 +6,23 @@
 import org.apache.maven.plugins.annotations.Mojo;
 import org.apache.maven.plugins.annotations.Parameter;
 
+/**
+ * This goal calls {@code dotnet pack} creating nuget packages ({@code *.nupgk}). The goal will
+ * call dotnet with {@code --no-build} as the project was already built in the {@code compile} phase
+ * by the {@link BuildMojo {@code build} goal}.
+ */
 @Mojo(name = "pack", defaultPhase = LifecyclePhase.PACKAGE)
 public class PackMojo extends AbstractDotnetMojo {
 
+    /**
+     * This parameter specifies a description for the package created.
+     */
     @Parameter(defaultValue = "${project.description}")
     private String description;
 
+    /**
+     * This parameter specifies a URL to be added tp the package as its source.
+     */
     @Parameter(defaultValue = "${project.scm.url}")
     private String repositoryUrl;
 

src/main/java/de/eitco/cicd/dotnet/TestMojo.java

@@ -18,16 +18,29 @@
 import java.util.Objects;
 
 
+/**
+ * This goal calls {@code dotnet test} to execute test. It will add the command line parameter {@code --no-build},
+ * since the {@code compile} phase will already be called before the {@code test} phase. It will always configure
+ * the {@code trx} logger and transform the results to a valid {@code junit} description - enabling ci servers to
+ * collect the test results in the default format for maven builds. The goal will honour the reactors failure behaviour.
+ */
 @Mojo(name = "test", defaultPhase = LifecyclePhase.TEST)
 public class TestMojo extends AbstractDotnetMojo {
 
     public static final String REACTOR_FAILURE_BEHAVIOR_FAIL_NEVER = "FAIL_NEVER";
     public static final String TEST_RESULT_EXTENSION = "trx";
     public static final String XSL_TRANSFORMATION = "xunit-to-junit.xsl";
 
+    /**
+     * This parameter specifies whether to skip the tests. Note that its property is the maven default property to
+     * skip tests.
+     */
     @Parameter(defaultValue = "false", property = "skipTests")
     private boolean skipTests;
 
+    /**
+     * This parameter specifies the directory where to write the test results to
+     */
     @Parameter(defaultValue = "target/test-results")
     private File testResultDirectory;
 

src/site/site.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<project xmlns="http://maven.apache.org/DECORATION/1.8.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/DECORATION/1.8.0 https://maven.apache.org/xsd/decoration-1.8.0.xsd"
+         name="dotnet-maven-plugin"
+         combine.self="override">
+
+    <skin>
+        <groupId>org.apache.maven.skins</groupId>
+        <artifactId>maven-fluido-skin</artifactId>
+        <version>1.12.0</version>
+    </skin>
+
+    <body>
+        <menu>
+            <item name="overview" href="plugin-info.html"/>
+        </menu>
+    </body>
+</project>