Complete psake documentation Phase 2.1

[HeyItsGilbert]

This commit completes Phase 2.1 of the documentation expansion plan by adding comprehensive best practices documentation for psake build scripts.

New Documentation Added:

• Best Practices category (category.json)

• Organizing Large Scripts (organizing-large-scripts.md)

  • File structure patterns (by category and build type)
  • Modular task files with complete examples
  • Using Include effectively with path validation
  • Shared utilities (file operations, logging, versioning)
  • Complete large project example

• Environment Management (environment-management.md)

  • Environment configuration patterns (inline, external files, JSON/YAML)
  • Environment-specific properties for dev/staging/prod
  • Conditional task execution using preconditions
  • Complete environment management example
  • CI/CD integration (GitHub Actions, Azure Pipelines)

• Secret Management (secret-management.md)

  • Environment variable patterns
  • Secure strings (PowerShell DPAPI)
  • Azure Key Vault integration
  • AWS Secrets Manager integration
  • HashiCorp Vault integration
  • Security best practices (never commit secrets, avoid logging)
  • Secure certificate handling

• Testing Build Scripts (testing-build-scripts.md)

  • Pester test setup and structure
  • Testing task dependencies
  • Mocking external commands (dotnet, az, AWS CLI)
  • Integration tests
  • Error handling tests
  • Test-friendly build script patterns
  • CI/CD integration

• Build Versioning Strategies (versioning-strategy.md)

  • Semantic versioning (SemVer) with pre-release labels
  • Git-based versioning from tags
  • GitVersion tool integration
  • CI build number versioning (GitHub Actions, Azure Pipelines)
  • Assembly version updates (.NET, Node.js)
  • Complete versioning example

Updated:

• sidebars.ts: Added Best Practices section between Build Types and CI Examples with all 5 new documentation pages properly linked

All documentation follows established patterns:

• Proper frontmatter with title and description
• Quick Start section with basic examples
• Complete working examples with full psakefile.ps1 code
• Multiple patterns and approaches
• Cross-references to related documentation
• "See Also" sections for navigation
• Comprehensive, production-ready code samples

[netlify]

✅ Deploy Preview for psake ready!

Name	Link
🔨 Latest commit	5b2d42c
🔍 Latest deploy log	https://app.netlify.com/projects/psake/deploys/6a9497bed0425300085490d3
😎 Deploy Preview	https://deploy-preview-26--psake.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

Adds a new Best Practices documentation section to the psake Docusaurus site (Phase 2.1), expanding guidance for structuring, securing, testing, and versioning psake build scripts, and wiring these pages into the sidebar navigation.

Changes:

• Added a new Best Practices sidebar category with links to 5 new documentation pages.
• Introduced five new best-practices guides covering organization, environment management, secret management, testing, and versioning strategies.
• Added a _category_.json to define the Best Practices docs category metadata and generated index.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
sidebars.ts	Adds the new “Best Practices” section and links the new docs into the sidebar.
docs/best-practices/category.json	Defines the Best Practices category label, position, and generated index metadata.
docs/best-practices/organizing-large-scripts.md	New guide describing modular build structures, Include usage, and shared utilities for large psake builds.
docs/best-practices/environment-management.md	New guide describing multi-environment configuration patterns and conditional task execution.
docs/best-practices/secret-management.md	New guide describing secret handling patterns and integrations (env vars, Key Vault, AWS Secrets Manager, Vault).
docs/best-practices/testing-build-scripts.md	New guide describing Pester-based testing strategies, mocking, and CI integration for psake scripts.
docs/best-practices/versioning-strategy.md	New guide describing SemVer, git-based versioning, CI build numbers, and version propagation to artifacts.

Suppressed comments (3)

docs/best-practices/secret-management.md:436

• This example also uses dotnet publish --api-key, which isn’t a valid dotnet publish argument. Since the point here is that logging the secret is bad, the command can omit the API key entirely to avoid implying this pattern is valid.

Task Deploy {
    Write-Host "Using API key: $ApiKey" -ForegroundColor Gray  # NEVER DO THIS!
    exec { dotnet publish --api-key $ApiKey }
}

docs/best-practices/secret-management.md:448

• This “good” example still passes the API key on the command line (dotnet publish --api-key ...), which both implies a non-existent dotnet publish option and can leak secrets via logs/process listings. Prefer setting an environment variable inside the exec block (or using a secret store) so the command line doesn’t contain the secret.

    # Use custom error message to avoid exposing secrets
    exec {
        dotnet publish --api-key $ApiKey
    } -errorMessage "Publish failed (check API key configuration)"

docs/best-practices/versioning-strategy.md:579

• This XML load has the same Get-Content issue as above; use -Raw to avoid passing a string array into the [xml] cast.

        [xml]$proj = Get-Content $project.FullName

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.