DroneHelper/README.md

<p align="right">
  <img src="http://forthebadge.com/images/badges/built-with-love.svg">
  <img src="http://forthebadge.com/images/badges/for-you.svg">
</p>

<p align="center">
  <a href="https://gitea.ocram85.com/OCram85/DroneHelper/">
    <img src="https://gitea.ocram85.com/OCram85/DroneHelper/raw/branch/master/assets/social-logo.png" alt="DroneHelper" />
  </a>
</p>

<h1 align="center">
  DroneHelper
</h1>

<p align="center">
  :hammer_and_wrench: Helper module for Drone.io based build pipelines.
</p>

<p align="center">
  <a href="https://drone.ocram85.com/OCram85/DroneHelper">
    <img src="https://drone.ocram85.com/api/badges/OCram85/DroneHelper/status.svg" alt="Master Branch Build Status">
  </a>
  <a href="https://www.powershellgallery.com/packages/DroneHelper">
    <img src="https://img.shields.io/powershellgallery/v/DroneHelper.svg?style=plastic" alt="PowershellGallery Published Version">
  </a>
  <a href="https://www.powershellgallery.com/packages/DroneHelper">
    <img src="https://img.shields.io/powershellgallery/vpre/DroneHelper.svg?label=latest%20preview&style=plastic" />
  </a>
  <a href="https://www.powershellgallery.com/packages/DroneHelper">
    <img src="https://img.shields.io/powershellgallery/dt/DroneHelper.svg?style=plastic" />
  </a>
</p>

## :key: General

The DroneHelper PowerShell module adds several features for `Gitea -> Drone.IO` based build pipelines. It's designed
to perform all needed tasks for PowerShell Module development like:

### Testing

- `Invoke-FileLinter` -> Runs basic FileLinter tests with console and log file output
- `Invoke-Linter` -> Runs PSScriptAnalyzer with embedded to custom profiles.
- `Invoke-UnitTest` -> Runs Pester tests including code coverage report with console and log file output.

### Build Pipeline
- `Send-PRComment` -> Takes all generated reports and reports them back as Pull Request Comment for a simplified overview.
- `Write-FailureStateFile`, `Invoke-Build` -> Marks the current pipeline run / build as failed if the previous steps also raised errors.

### Helper

- `New-Docs`, `Update-Docs` -> Automatically updates the markdown based docs generated form your Comment Based Help blocks in your functions


### Building & Publishing

- `Update-ModuleMeta` -> Updates the `ModuleVersion` + `Prerelease` properties wit the current git tag.
- `Merge-ModuleRoot` -> Takes all single file functions and merges them into a single `*.psm1` file.
- `New-BuildPackage` -> Creates a new build artifact for an alternate publishing target like a Gitea release.

To use these features, all you have to do, is follow the `.drone.yml` template:

### `.drone.yml` Template

```yaml
---
kind: pipeline
type: docker
name: "Build Pipeline"

trigger:
  branch:
    exclude:
      - droneDocs/*

steps:
  - name: "Pwsh FileLinter"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    failure: ignore
    environment:
      EXCLUDE: "(.exe|.dll|.ico|.gitkeep)"
    commands:
      - |
        apt-get update
        apt-get install -y file

      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module 'DroneHelper' -ErrorAction 'Stop';
          Invoke-FileLinter
        }"

  - name: "ScriptAnalyzer"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    failure: ignore
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Invoke-Linter
        }"

  - name: "Pester"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    failure: ignore
    commands:
      - |
        apt-get update
        apt-get install -y file

      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Invoke-UnitTest -Verbosity 'Detailed' -ExcludeTag 'Integration'
        }"

  - name: "PRComment"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    failure: ignore
    environment:
      GITEA_TOKEN:
        from_secret: GITEA_TOKEN
      CUSTOM_PIPELINE_STATE: true
      LOG_FILES: "build/*.log"
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Send-PRComment
        }"
    when:
      event:
        include:
          - pull_request

  - name: "buildState"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Invoke-BuildState
        }"

---
kind: pipeline
type: docker
name: "Publish Pipeline"

depends_on:
  - "Build Pipeline"

trigger:
  event:
    - tag

steps:
  - name: BuildArtifacts
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    #failure: ignore
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Update-ModuleMeta -Verbose
        }"
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          New-BuildPackage -Verbose
        }"

  - name: GiteaRelease
    image: plugins/gitea-release
    settings:
      api_key:
        from_secret: GITEA_TOKEN
      base_url: https://gitea.ocram85.com
      files:
        - "bin/${DRONE_REPO_NAME}.zip"
        - "bin/PSModule.zip"
      title: "${DRONE_TAG}"
      note: CHANGELOG.md

  - name: "PublishModule"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    #failure: ignore
    environment:
      NuGetToken:
        from_secret: PSGallery
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Invoke-Publish -Verbose
        }"

---
kind: pipeline
type: docker
name: "Update Docs"

depends_on:
  - "Build Pipeline"

trigger:
  event:
    exclude:
      - pull_request
  branch:
    include:
      - master

steps:
  - name: "Update Docs"
    image: mcr.microsoft.com/dotnet/sdk:6.0-focal
    commands:
      - |
        pwsh -NonInteractive -c "& {
          Install-Module -Name 'DroneHelper' -Repository 'PSGallery' -ErrorAction 'Stop';
          Import-Module -Name 'DroneHelper' -ErrorAction 'Stop';
          Install-ModuleDependency;
          Update-Docs -Verbose
        }"

  - name: "push commit"
    image: appleboy/drone-git-push
    settings:
      remote_name: origin
      branch: "droneDocs/${DRONE_COMMIT:0:8}"
      local_ref: droneDocs
      commit: true
      commit_message: "docs updated by drone [CI SKIP]"
      author_name: drone
      author_email: noreply@ocram85.com
      force: true
```