Skip to content

Latest commit

 

History

History
133 lines (100 loc) · 4.99 KB

upgrade-notes.md

File metadata and controls

133 lines (100 loc) · 4.99 KB
Raw

Upgrade notes

This document contains notes to help upgrade from previous versions of the PSRule extension.

Upgrade to v2.8.0

Follow these notes to upgrade from previous versions to v2.8.0.

@2 task versions

From PSRule v2.8.0 the @1 and @0 task versions are deprecated and will be removed from v3.0.0. The @2 task versions are now the default task versions.

To upgrade to the latest task versions to use @2 or higher.

  • ps-rule-install@2 instead of ps-rule-install@1.
  • ps-rule-assert@2 instead of ps-rule-assert@1.

Upgrade to v1.5.0

Follow these notes to upgrade from previous versions to v1.5.0.

Node 10 extension handler

Prior to v1.5.0, the Node 6 extension handler was used. From March 31st 2022 the Node 6 extension handler will be removed from Azure DevOps. Pipelines using the Node 6 extension handler will not work after this date.

To upgrade to the latest version update task versions to use v1 or higher. To do this use the @1 suffix on the task name.

  • ps-rule-install@1 instead of ps-rule-install@0.
  • ps-rule-assert@1 instead of ps-rule-assert@0.

For example:

# Install PSRule.Rules.Azure from the PowerShell Gallery
- task: ps-rule-install@1
  inputs:
    module: PSRule.Rules.Azure    # Install PSRule.Rules.Azure from the PowerShell Gallery.

# Run analysis
- task: ps-rule-assert@1
  inputs:
    modules: 'PSRule.Rules.Azure' # Analyze objects using the rules within the PSRule.Rules.Azure PowerShell module.

Upgrade to v0.5.0

Follow these notes to upgrade from extension version v0.4.0 to v0.5.0. For a list of upstream changes to the PSRule engine see change log.

Repository analysis

Previously in v0.4.0 or prior using inputType: repository on the ps-rule-assert task would:

  • Emit a System.IO.DirectoryInfo object for the repository root.
  • Emit a System.IO.FileInfo object for each file in the repository.

This allows rules to be run for the repository and each repository file.

For example:

# Synopsis: Check for recommended community files
Rule 'GitHub.Community' -Type 'System.IO.DirectoryInfo' {
    $requiredFiles = @(
        'README.md'
        'LICENSE'
        'CODE_OF_CONDUCT.md'
        'CONTRIBUTING.md'
        '.github/CODEOWNERS'
        '.github/PULL_REQUEST_TEMPLATE.md'
    )
    Test-Path -Path $TargetObject.FullName;
    for ($i = 0; $i -lt $requiredFiles.Length; $i++) {
        $filePath = Join-Path -Path $TargetObject.FullName -ChildPath $requiredFiles[$i];
        $Assert.Create((Test-Path -Path $filePath -PathType Leaf), "$($requiredFiles[$i]) does not exist");
    }
}

# Synopsis: Check for license in code files
Rule 'OpenSource.License' -Type 'System.IO.FileInfo' -If { $TargetObject.Extension -in '.cs', '.ps1', '.psd1', '.psm1' } {
    $commentPrefix = "`# ";
    if ($TargetObject.Extension -eq '.cs') {
        $commentPrefix = '// '
    }
    $header = GetLicenseHeader -CommentPrefix $commentPrefix;
    $content = Get-Content -Path $TargetObject.FullName -Raw;
    $content.StartsWith($header);
}

In v0.5.0, repository analysis switched to using built-in File input type support. This change provides a more efficient scan of files and allows exclusion of files by path spec.

Two breaking changes occurred as a result of this.

  1. The repository root uses the type PSRule.Data.RepositoryInfo instead of System.IO.DirectoryInfo. Rules that previously used -Type 'System.IO.DirectoryInfo' should now use -Type 'PSRule.Data.RepositoryInfo'.
  2. Each repository file now uses the type PSRule.Data.InputFileInfo instead of System.IO.FileInfo. Additionally, PSRule automatically uses the file extension for type binding. Rules that previously used -Type 'System.IO.FileInfo' should now use the file extension. i.e. -Type '.ps1', '.cs', '.js'.

For example:

# Synopsis: Check for recommended community files
Rule 'OpenSource.Community' -Type 'PSRule.Data.RepositoryInfo' {
    $Assert.FilePath($TargetObject, 'FullName', @('CHANGELOG.md'));
    $Assert.FilePath($TargetObject, 'FullName', @('LICENSE'));
    $Assert.FilePath($TargetObject, 'FullName', @('CODE_OF_CONDUCT.md'));
    $Assert.FilePath($TargetObject, 'FullName', @('CONTRIBUTING.md'));
    $Assert.FilePath($TargetObject, 'FullName', @('SECURITY.md'));
    $Assert.FilePath($TargetObject, 'FullName', @('README.md'));
    $Assert.FilePath($TargetObject, 'FullName', @('.github/CODEOWNERS'));
    $Assert.FilePath($TargetObject, 'FullName', @('.github/PULL_REQUEST_TEMPLATE.md'));
}

# Synopsis: Check for license in code files
Rule 'OpenSource.License' -Type '.cs', '.ps1', '.psd1', '.psm1' {
    $Assert.FileHeader($TargetObject, 'FullName', @(
        'Copyright (c) Microsoft Corporation.'
        'Licensed under the MIT License.'
    ));
}

To read more about the new FilePath and FileHeader assertion helpers see about_PSRule_Assert