A Code and Style Guide

[fourthborngoose]

Mr. Parker.
Does this look kind of like a good beginning to a Code and Style Guide? I am new to this and I really REALLY like your tool, and I hope to adapt this to my internal processes by adding new apps. You talked about it in here ( #586 )

✳️ Evergreen Application Contribution Code and Style Guide

🎯 Purpose

This guide provides internal standards and best practices for adding new application definitions to Evergreen, enabling consistent, secure, and maintainable contributions from our team.

It is based on guidance provided by the Evergreen creator and extends it with local conventions to support:

• Contributor onboarding
• Reliable update logic (no HTML parsing)
• Code signing and audit readiness

---

📁 Evergreen Project Overview

• Apps Directory: Contains PowerShell .ps1 scripts for each supported application.
• Manifests Directory: Contains version metadata for Evergreen to read from cache.
• Public Module: Imports and exposes apps through Get-EvergreenApp, Save-EvergreenApp, etc.

---

🧩 Contribution Workflow (Standard)

1. Fork the Evergreen repository

   git clone https://github.com/aaronparker/evergreen.git
   cd evergreen
   git checkout -b feature/add-app-YourAppName

2. Create New App Script

   • Place in: apps/YourAppName.ps1
   • Follow style and formatting rules below

3. Create Matching Manifest (Optional)

   • Place in: manifests/YourAppName.json (used for cached version data)

4. Test Your Code

   Import-Module .\Evergreen.psd1
   Get-EvergreenApp -Name YourAppName
   Save-EvergreenApp -Name YourAppName -Path .\Output\

5. Sign All Commits

   git config commit.gpgsign true
   git commit -S -m "Add support for YourAppName"

6. Push and Submit PR

   git push origin feature/add-app-YourAppName
   # Then open a pull request on GitHub

---

✅ Coding Standards

File: apps/YourAppName.ps1

• Must define a Get-YourAppName function.
• Output must use New-EvergreenAppResult for standardized formatting.
• Should support both Get-EvergreenApp and Save-EvergreenApp workflows.

Mandatory Structure

function Get-YourAppName {
    [CmdletBinding()]
    param ()

    # Example source logic
    $response = Invoke-RestMethod -Uri "https://api.vendor.com/releases/latest"

    # Parse and output
    New-EvergreenAppResult -Name "YourAppName" -Version $response.version -Uri $response.downloadUrl
}

✅ Acceptable Methods

Method	Allowed?	Notes
GitHub API (REST)	✅ Yes	Preferred if vendor hosts on GitHub
JSON/XML Release Feed	✅ Yes	Structured feed (e.g. REST or OData)
Regex from .js or config	⚠️ Avoid	Only if JSON/XML or API unavailable
Parsing raw HTML	❌ No	Explicitly prohibited

✅ Output Requirements

Field	Required	Format/Type
Name	✅ Yes	String (App name)
Version	✅ Yes	x.y.z or yyyy.mm
URI	✅ Yes	Direct download link
Architecture	Optional	x64, x86, arm if applicable

---

🧪 Testing Requirements

• Use Pester if adding test coverage
• Validate Get-EvergreenApp -Name YourAppName returns expected result
• Ensure Save-EvergreenApp successfully downloads installer

---

🔐 Security and Compliance

• No hardcoded credentials or API keys
• All web requests must use HTTPS
• Use of Invoke-RestMethod or Invoke-WebRequest must include user-agent headers

---

🧾 Naming Conventions

• File name must match YourAppName.ps1
• Internal function: Get-YourAppName
• ID used in manifest: camelCase or dash-separated your-app-name

---

📋 Example Projects to Reference

• apps/NotepadPlusPlus.ps1
• apps/VLCMediaPlayer.ps1
• apps/AdobeAcrobatReaderDC.ps1

---

📬 Contributor Notes

• Commit messages must be conventional: Add:, Fix:, Update:
• All PRs must pass the CI workflow in Evergreen repo
• Multiple apps can be added via a single PR, but keep commits isolated

---

🔄 Evergreen Pull Request Checklist

---