Workflow update automation limitation

Due to GitHub security restrictions, workflow files located in .github/workflows/ (e.g., CI.yml, sync-standards.yml) cannot be automatically modified via PRs or pushes generated by bots or GitHub Actions, unless the token used has workflows: write permission in the target repository.

This means:

Changes to central workflows must be updated manually in child repositories.
Even if you use repository templates, scripts, or bots, workflow updates require manual intervention by each project's maintainers.
If you use a Personal Access Token (PAT) with repo and workflow permissions, it is possible to automate updates, but this requires additional configuration and is not recommended for all cases.

Recommendation: When a central workflow is updated, notify the maintainers of child repositories so they can manually copy the updated file into their project.

Evergine standards

Shared standards and static assets for Evergine repositories — including the NuGet package icon, license file, and synchronization tools for keeping all repositories aligned.

Overview

This repository centralizes build standards shared across all Evergine repositories.
Its purpose is to ensure consistency and reduce maintenance overhead caused by duplicated scripts, templates, and configuration files.

Typical consumers include:

Core libraries published as NuGet packages.
Satellite tools and prefabs distributed in separate repositories.
Future repositories that should automatically stay aligned with global standards.

Repository structure

/
├─ .github/
│  ├─ actions/
│  │  ├─ addon-generate-assets/                   # Composite action for add-on asset generation
│  │  ├─ binding-generate-bindings-dotnet/        # Composite action for binding generation
│  │  ├─ binding-generate-nugets-dotnet/          # Composite action for NuGet generation
│  │  ├─ commit-and-push-or-pr-update/            # Composite action for commit/push/PR automation
│  │  └─ send-notification-email/                 # Composite action for email notifications
│  └─ workflows/
│     ├─ _check-changes-since-last-run.yml        # Reusable workflow for change detection
│     ├─ _sync-standards-reusable.yml             # Reusable GitHub Actions workflow (sync)
│     ├─ _test-sync-standards.yml                 # Reusable test workflow
│     ├─ addon-common-ci.yml                      # Reusable CI workflow for add-ons
│     ├─ addon-simple-cd.yml                      # Reusable CD workflow for add-ons
│     ├─ binding-common-ci.yml                    # Reusable CI workflow for bindings (common)
│     ├─ binding-simple-cd.yml                    # Reusable CD workflow for pure .NET bindings
│     ├─ binding-xml-cd.yml                       # Reusable CD workflow for bindings with XML
│     ├─ ci.yml                                   # Main CI workflow
│     └─ sync-standards.yml                       # Template workflow for consumer repos
├─ assets/
│  └─ nuget-icon.png                              # Official NuGet package icon (512x512)
├─ LICENSE                                        # Canonical license file
├─ README.md                                      # This documentation
├─ scripts/
│  ├─ add-ons/
│  │  └─ Generate-Assets-AddOn.ps1                # Template for add-on asset generation
│  ├─ binding/
│  │  └─ Generate-Bindings-DotNet.ps1             # Template for .NET binding generators
│  ├─ common/
│  │  ├─ Generate-NuGets-DotNet.ps1               # Unified NuGet generation script
│  │  └─ Helpers.ps1                              # Shared PowerShell helpers
│  ├─ download-sync-script.ps1                    # Helper to download sync script locally
│  └─ sync-standards.ps1                          # Synchronization script (PowerShell 7+)
├─ sync-manifest.json                             # Manifest defining which files to sync
├─ temp-binding-analysis/                         # Temporary binding analysis repositories
├─ tests/                                         # Test suite for all components
└─ workflows/
   ├─ add-ons/
   │  ├─ template-cd-nightly.yml                  # Template for nightly add-on builds
   │  ├─ template-cd-preview.yml                  # Template for preview add-on releases
   │  ├─ template-cd-stable.yml                   # Template for stable add-on releases
   │  └─ template-common-ci.yml                   # Template for add-on CI
   └─ binding/
      ├─ template-common-ci.yml                   # Template for binding CI
      ├─ template-simple-cd.yml                   # Reference template for pure .NET bindings
      └─ template-xml-cd.yml                      # Reference template for bindings with XML

## Add-on automation and templates

This repository provides reusable workflows and composite actions to automate the build, packaging, and publication of add-ons that include both assets (.wepkg) and optional NuGet packages.

### Key workflows
- **addon-simple-cd.yml**: For add-ons with asset generation and optional NuGet packaging.
- **addon-common-ci.yml**: Common CI workflow for add-ons.

### Composite actions
- **addon-generate-assets**: Standardized add-on asset generation.
- **binding-generate-nugets-dotnet**: Standardized NuGet packaging (shared with bindings).
- **send-notification-email**: Email notifications for failures.

### Reference templates
Find ready-to-use templates in `workflows/add-ons/`:
- `template-common-ci.yml`: Example CI workflow for add-ons.
- `template-cd-nightly.yml`: Example for nightly builds with change detection.
- `template-cd-preview.yml`: Example for preview releases.
- `template-cd-stable.yml`: Example for stable releases.

### Change detection automation
Add-on workflows include change detection to avoid unnecessary builds. The `_check-changes-since-last-run.yml` workflow checks if there are changes since the last successful run, ensuring efficient resource usage.

---

## Binding automation and templates

This repository provides reusable workflows and composite actions to automate the build, packaging, and publication of bindings (both pure .NET and those requiring XML updates).

### Key workflows
- **binding-simple-cd.yml**: For pure .NET bindings (no XML update required).
- **binding-xml-cd.yml**: For bindings that require downloading and comparing XML files before generating and publishing NuGets.
- **binding-common-ci.yml**: Common CI workflow for bindings.

### Composite actions
- **binding-generate-bindings-dotnet**: Standardized binding generation.
- **binding-generate-nugets-dotnet**: Standardized NuGet packaging.
- **commit-and-push-or-pr-update**: Automates commit/push/PR for updated files (e.g., XML), supporting direct commit or PR creation depending on repo protection.

### Reference templates
Find ready-to-use templates in `workflows/binding/`:
- `template-simple-cd.yml`: Example for pure .NET bindings.
- `template-xml-cd.yml`: Example for bindings with XML update logic.

### XML update automation
Bindings that require XML updates use the composite action `commit-and-push-or-pr-update` to automatically commit the new XML file or open a PR if direct push is not allowed. This ensures the repository stays up to date with upstream XML definitions with minimal manual intervention.


---

## Add-on repositories support

This repository includes specialized scripts for **add-on repositories** that generate Evergine add-ons with assets and optional NuGet packages. Add-on repositories can use the "add-on" group by adding it to their `.standards.override.json`:

```json
{
  "schema": "2",
  "groups": ["core", "add-on"]
}

Generate-Assets-AddOn.ps1

A parametrized template script for generating add-on assets (.wepkg packages). It supports Evergine asset projects and standardizes the build process across add-on repositories.

Usage

./scripts/Generate-Assets-AddOn.ps1 `
  -AssetsProject "YourAddon.Assets/YourAddon.Assets.csproj" `
  [-Version "1.0.0"] `
  [-Revision "123"] `
  [-VersionSuffix "preview"] `
  [-BuildConfiguration "Release"] `
  [-BuildVerbosity "normal"] `
  [-OutputFolder "wepkgs"] `
  [-VersionToken "2025.0.0.0-preview"]

Parameters

Parameter	Description	Default	Required
`AssetsProject`	Path to the assets .csproj file	-	Yes
`Version`	Direct version string for packages (add-ons)	-	No*
`Revision`	Revision for date-based version	-	No*
`VersionSuffix`	Version suffix (e.g., "preview", "nightly")	-	No
`BuildConfiguration`	Build configuration (Debug/Release)	`Release`	No
`BuildVerbosity`	MSBuild verbosity level	`normal`	No
`OutputFolder`	Output directory for .wepkg files	`wepkgs`	No
`VersionToken`	Version token to replace in .wespec files	`2025.0.0.0-preview`	No

Either Version or Revision can be provided for different versioning strategies.

Example

# Add-on style with direct version
./scripts/Generate-Assets-AddOn.ps1 `
  -AssetsProject "MyAddon.Assets/MyAddon.Assets.csproj" `
  -Version "1.0.0-preview"

# Nightly style with date-based version
./scripts/Generate-Assets-AddOn.ps1 `
  -AssetsProject "MyAddon.Assets/MyAddon.Assets.csproj" `
  -Revision 123 `
  -VersionSuffix "nightly"

Binding repositories support

This repository includes specialized scripts for binding repositories that generate C# bindings for native libraries. Binding repositories can use the "binding" group by adding it to their .standards.override.json:

{
  "schema": "2",
  "groups": ["core", "binding"]
}

Generate-Bindings-DotNet.ps1

A parametrized template script that replaces duplicated Generate-Bindings.ps1 scripts across binding repositories. It supports .NET-based binding generators.

Usage

./scripts/Generate-Bindings-DotNet.ps1 `
  -GeneratorProject "MyLibGen/MyLibGen/MyLibGen.csproj" `
  -GeneratorName "MyLib" `
  [-BuildConfiguration "Release"] `
  [-BuildVerbosity "normal"] `
  [-TargetFramework "net8.0"] `
  [-RuntimeIdentifier "win-x64"]

Parameters

Parameter	Description	Default	Required
`GeneratorProject`	Path to the generator .csproj file	-	Yes
`GeneratorName`	Name used for display and logging	-	Yes
`BuildConfiguration`	Build configuration (Debug/Release)	`Release`	No
`BuildVerbosity`	MSBuild verbosity level	`normal`	No
`TargetFramework`	.NET target framework	`net8.0`	No
`RuntimeIdentifier`	Runtime identifier (e.g., win-x64)	`win-x64`	No

Example

# Generic binding generation
./scripts/Generate-Bindings-DotNet.ps1 `
  -GeneratorProject "MyLibGen/MyLibGen/MyLibGen.csproj" `
  -GeneratorName "MyLib"

Generate-NuGets-DotNet.ps1

A unified script for generating NuGet packages from .NET projects in binding repositories. This script replaces duplicated NuGet generation logic and ensures consistency across all bindings.

The script supports dependency projects that need to be built first (to resolve dependencies like DLLs) but won't generate NuGet packages themselves. Only projects listed in the main Projects parameter will produce NuGet packages.

Usage

# Binding style (date-based version with revision)
./scripts/Generate-NuGets-DotNet.ps1 -Revision 123 -Projects "SampleBinding/Evergine.Bindings.Sample/Evergine.Bindings.Sample.csproj"

# Add-on style (direct version)
./scripts/Generate-NuGets-DotNet.ps1 -Version "3.4.22.288-local" -Projects @("Source/Evergine.SampleAddon/Evergine.SampleAddon.csproj", "Source/Evergine.SampleAddon.Editor/Evergine.SampleAddon.Editor.csproj")

# Using custom helpers path
./scripts/Generate-NuGets-DotNet.ps1 -Revision 123 -Projects "test.csproj" -HelpersPath "C:/Scripts/MyHelpers.ps1"

# Using legacy symbol format
./scripts/Generate-NuGets-DotNet.ps1 -Version "1.0.0" -Projects "test.csproj" -SymbolsFormat "symbols.nupkg"

Parameters

Parameter	Description	Default	Required
`Version`	Direct version string for packages (add-ons)	-	Yes*
`Revision`	Revision for date-based version (bindings)	-	Yes*
`Projects`	Array of .csproj paths to pack (string or array)	-	Yes
`DependencyProjects`	Array of .csproj paths to build first (dependencies) but won't generate NuGet packages	`@()`	No
`OutputFolderBase`	Base folder for NuGet package output	`nupkgs`	No
`BuildVerbosity`	dotnet verbosity level	`normal`	No
`BuildConfiguration`	Build configuration (Release/Debug)	`Release`	No
`IncludeSymbols`	Include debug symbols in packages	`false`	No
`SymbolsFormat`	Symbol package format: 'snupkg' or 'symbols.nupkg'	`snupkg`	No
`HelpersPath`	Path to Helpers.ps1 file	(auto)	No

Either Version or Revision must be provided, but not both.

Example

# Binding style (date-based version with revision)
./scripts/Generate-NuGets-DotNet.ps1 -Revision 123 -Projects "SampleBinding/Evergine.Bindings.Sample/Evergine.Bindings.Sample.csproj"

# Add-on style (direct version)
./scripts/Generate-NuGets-DotNet.ps1 -Version "3.4.22.288-local" -Projects @("Source/Evergine.SampleAddon/Evergine.SampleAddon.csproj", "Source/Evergine.SampleAddon.Editor/Evergine.SampleAddon.Editor.csproj")

# Building dependency projects but only packing main projects
./scripts/Generate-NuGets-DotNet.ps1 -Revision 123 -Projects "MainProject.csproj" -DependencyProjects @("DependencyProject1.csproj", "DependencyProject2.csproj")

Note on runner selection in reusable workflows

All reusable workflows in .github/workflows support a runner-os input, allowing you to select the GitHub Actions runner OS (e.g., ubuntu-latest, windows-latest) for each job. By default, this is set to ubuntu-latest, but you can override it when calling the workflow from your repository if you need a different environment.

Example usage

Composite action for add-on asset generation

- name: Generate add-on assets
  uses: EvergineTeam/evergine-standards/.github/actions/addon-generate-assets@main
  with:
    script-path: ./scripts/Generate-Assets-AddOn.ps1
    assets-project: YourAddon.Assets/YourAddon.Assets.csproj
    version: ${{ ... }}      # Or revision: ${{ ... }} as needed
    version-suffix: preview
    build-configuration: Release
    build-verbosity: normal
    output-folder: wepkgs
    version-token: "2025.0.0.0-preview"

Composite action for NuGet generation

- name: Generate NuGets (.NET)
  uses: EvergineTeam/evergine-standards/.github/actions/binding-generate-nugets-dotnet@main
  with:
    script-path: ./scripts/Generate-NuGets-DotNet.ps1
    projects: path/to/project1.csproj,path/to/project2.csproj
    dependency-projects: path/to/dependency1.csproj,path/to/dependency2.csproj  # Optional: projects to build but not pack
    version: ${{ ... }}      # Or revision: ${{ ... }} as needed
    output-folder: nupkgs
    build-configuration: Release
    build-verbosity: normal
    include-symbols: false
    symbols-format: snupkg

Composite action for email notifications

- name: Send failure notification
  if: ${{ failure() }}
  uses: EvergineTeam/evergine-standards/.github/actions/send-notification-email@main
  with:
    sendgrid-token: ${{ secrets.WAVE_SENDGRID_TOKEN }}
    from-email: ${{ secrets.EVERGINE_EMAIL }}
    to-emails: ${{ secrets.EVERGINE_EMAILREPORT_LIST }}
    subject: Build failed - ${{ github.repository }}
    additional-info: |
      Additional context about the failure

Composite action for commit/push/PR automation (XML update)

- name: Commit, push or PR XML update
  uses: EvergineTeam/evergine-standards/.github/actions/commit-and-push-or-pr-update@main
  with:
    commit_message: "Update XML file for binding MyBinding"
    mode: auto
    labels: xml,standards
    pr_branch_name: chore/update-xml-MyBinding
    pr_title: "Update XML for MyBinding"
    pr_body: "Automated update of XML file for binding MyBinding."

Reusable workflow for add-on CI

jobs:
  build:
    uses: EvergineTeam/evergine-standards/.github/workflows/addon-common-ci.yml@main
    with:
      configuration: Release

Reusable workflow for binding CI

jobs:
  build:
    uses: EvergineTeam/evergine-standards/.github/workflows/binding-common-ci.yml@main
    with:
      configuration: Release

Synchronization and reuse in native binding repositories

Native binding repositories (e.g., ktx, imgui) can reuse the .NET scripts and actions provided here for their managed components. To do so, ensure the scripts are available in the repo (via sync or direct reference) and invoke them as shown above. This allows unified NuGet generation even in mixed native/.NET bindings.

Synchronization workflow

Evergine repositories can automatically stay up to date with shared files using the provided GitHub Actions workflow.

1. Reusable workflow (centralized)

The reusable workflow is defined here:

.github/workflows/_sync-standards-reusable.yml

It handles the synchronization logic:

Downloads the sync script dynamically from this repository (scripts/sync-standards.ps1).
Downloads and applies the manifest (sync-manifest.json).
Detects changes.
Commits or opens a Pull Request (depending on protection rules).

Repositories consume it using:

uses: EvergineTeam/evergine-standards/.github/workflows/_sync-standards-reusable.yml@main

The reusable workflow executes in the context of the target repository, not in evergine-standards.

2. Wrapper workflow (per repository)

Each repository includes a lightweight wrapper (synchronized via the manifest):

name: Sync standards

on:
  workflow_dispatch:
  schedule:
    - cron: "0 2 1 * *"  # First day of the month at 02:00 UTC

jobs:
  sync:
    uses: EvergineTeam/evergine-standards/.github/workflows/_sync-standards-reusable.yml@main
    with:
      org:  "EvergineTeam"
      repo: "evergine-standards"
      ref:  "main"
      target_branch: "main"
      script_path: "sync-standards.ps1"
      commit_message: "auto: sync standard files [skip ci]"
      mode: "auto"
    secrets: inherit

This wrapper can be customized (e.g., cron schedule or target branch).
If you customize it, you can prevent future overwrites using a .standards.override.json file.

Parameters for the reusable workflow

The reusable workflow accepts the following parameters in the with section:

Parameter	Description	Default	Required
`org`	Source GitHub organization	`EvergineTeam`	No
`repo`	Source repository name	`evergine-standards`	No
`ref`	Git reference (branch, tag, or SHA)	`main`	No
`target_branch`	Branch to apply changes to	`main`	No
`script_path`	Path where to download the sync script	`sync-standards.ps1`	No
`commit_message`	Custom commit message for changes	Uses `STANDARDS_COMMIT_MESSAGE` variable or default fallback	No
`mode`	Commit strategy: `auto` (push then PR if needed) or `pr` (always PR)	`auto`	No
`dry_run`	Show what would be done without making changes	`false`	No

Note: For commit_message, the workflow uses a priority fallback system:

Explicit commit_message parameter (if provided)

STANDARDS_COMMIT_MESSAGE organization/repository variable (if defined)

Default: "auto: sync standard files [skip ci]"

The STANDARDS_COMMIT_MESSAGE variable can be defined at organization level and overridden per repository in Settings → Secrets and variables → Actions → Variables tab.

Synchronization script (`scripts/sync-standards.ps1`)

The PowerShell script performs the actual synchronization.

Local override option

Consumer repositories can use a local version of the script for special cases:

Using the download helper

The easiest way to get a local copy is using the download helper:

# Download latest version to current directory
.\scripts\download-sync-script.ps1

# Download to specific location
.\scripts\download-sync-script.ps1 -Destination "tools\sync-standards.ps1"

# Download specific version
.\scripts\download-sync-script.ps1 -Ref "v1.2.0"

Manual setup

Alternatively, you can manually place a local copy:

Place the script at the path specified in script_path parameter (default: sync-standards.ps1)
Update your workflow's script_path parameter to point to your local copy

Important considerations

Automatic detection: The workflow will automatically detect and use the local version instead of downloading
No automatic updates: Once you use a local version, you will not receive newer versions automatically
Manual maintenance: You're responsible for updating the local script when needed
Override workflow parameter: Remember to set script_path in your wrapper workflow to match your local file location

Usage

pwsh ./scripts/sync-standards.ps1 [-Org EvergineTeam] [-Repo evergine-standards] [-Ref main]

Optional parameters:

Parameter	Description
`-Org`	Source GitHub organization (default: `EvergineTeam`)
`-Repo`	Source repository (default: `evergine-standards`)
`-Ref`	Git reference (branch, tag, or SHA; default: `main`)
`-SourcePath`	Local folder instead of remote source (for local testing)
`-DryRun`	Prints actions without writing files

The script:

Loads the sync-manifest.json.
Applies optional per-repository overrides.
Downloads and writes the corresponding files.
Reports updated and ignored items.

The script never commits or pushes.
Commits are performed by the GitHub Actions workflow.

Download helper (`scripts/download-sync-script.ps1`)

A convenience script to download the sync script to your local repository for development or testing.

Usage

pwsh ./scripts/download-sync-script.ps1 [-Org EvergineTeam] [-Repo evergine-standards] [-Ref main] [-Destination path] [-Force]

Parameters

Parameter	Description	Default
`-Org`	Source GitHub organization	`EvergineTeam`
`-Repo`	Source repository name	`evergine-standards`
`-Ref`	Branch, tag, or commit to download from	`main`
`-Destination`	Local path where to save the script	`sync-standards.ps1`
`-Force`	Overwrite existing file without prompting	`false`

Examples

# Download latest to current directory
.\scripts\download-sync-script.ps1

# Download to tools directory  
.\scripts\download-sync-script.ps1 -Destination "tools\sync-standards.ps1"

# Download specific version
.\scripts\download-sync-script.ps1 -Ref "v1.2.0" -Force

Manifest format (`sync-manifest.json`)

The manifest defines which files are distributed to all repositories using schema v2 with groups:

{
  "schema": "2",
  "defaultGroups": ["core"],
  "groups": {
    "core": [
      { "src": "LICENSE", "dst": "LICENSE" },
      { "src": "assets/nuget-icon.png", "dst": "assets/nuget-icon.png" },
      { "src": "tools/sync-standards.ps1", "dst": "tools/sync-standards.ps1" }
    ],
    "add-on": [
      { "src": "scripts/add-ons/Generate-Assets-AddOn.ps1", "dst": "scripts/Generate-Assets-AddOn.ps1", "overwrite": "always" },
      { "src": "scripts/common/Generate-NuGets-DotNet.ps1", "dst": "scripts/Generate-NuGets-DotNet.ps1", "overwrite": "always" },
      { "src": "scripts/common/Helpers.ps1", "dst": "scripts/Helpers.ps1", "overwrite": "always" }
    ],
    "binding": [
      { "src": "scripts/binding/Generate-Bindings-DotNet.ps1", "dst": "scripts/Generate-Bindings-DotNet.ps1", "overwrite": "always" },
      { "src": "scripts/common/Generate-NuGets-DotNet.ps1", "dst": "scripts/Generate-NuGets-DotNet.ps1", "overwrite": "always" },
      { "src": "scripts/common/Helpers.ps1", "dst": "scripts/Helpers.ps1", "overwrite": "always" }
    ],
    "docs": [
      { "src": "templates/README.md", "dst": "README.md", "overwrite": "ifMissing" },
      { "src": "docs/contributing.md", "dst": "CONTRIBUTING.md" }
    ]
  }
}

Properties:

schema: Must be "2"
defaultGroups: Array of group names to use when no override file specifies groups
groups: Object containing named groups, each with an array of files
Groups allow different repositories to receive different sets of files based on their role/type

File Properties:

src: Path in this repository.
dst: Destination path in the target repository.
overwrite:
- "always" → Replace existing files (default).
- "ifMissing" → Create only if the file does not exist (used for local customization).

Overrides (`.standards.override.json`)

Each repository can define exceptions and remappings:

{
  "schema": "2",
  "groups": ["core", "docs"],
  "remap": {
    "assets/nuget-icon.png": {
      "dst": "src/Branding/nuget-icon.png",
      "overwrite": "ifMissing"
    },
  },
  "ignore": [
    "templates/*"
  ]
}

Override Properties:

schema: Must be "2"
groups: Array of group names to sync instead of defaultGroups from manifest
remap: Change file destinations or overwrite policies
- Key = src or dst (from manifest)
- Value = new destination (string) or object { dst, overwrite }
ignore: Array of file paths to skip with full wildcard pattern support
- Wildcards supported:
  - * - Matches any number of characters
  - ? - Matches exactly one character
  - [abc] - Matches any character in the set
  - [a-z] - Matches any character in the range
- Examples:
  - "*.tmp" - All .tmp files
  - "temp/*" - Everything inside temp folder
  - "*debug*.log" - Files containing "debug" with .log extension
  - "test-?.json" - Files like test-1.json, test-a.json, etc.
  - "docs/draft[0-9][0-9].md" - Files like docs/draft01.md, docs/draft99.md

Group selection examples

{
  "schema": "2",
  "groups": ["core"]
}

Only synchronizes files from the "core" group.

{
  "schema": "2", 
  "groups": ["core", "ci", "docs"]
}

Synchronizes files from multiple groups.

Group selection behavior

The script follows this priority order for determining which groups to sync:

Override file with groups: If an override file exists and contains a groups property, those groups are used
Manifest defaultGroups: If no override file exists OR the override file doesn't specify groups, the manifest's defaultGroups are used
Error: If neither exists, the script throws an error

Examples:

// Override with groups - uses specified groups
{
  "schema": "2",
  "groups": ["core", "docs"]
}

// Override without groups - falls back to defaultGroups
{
  "schema": "2",
  "remap": { "LICENSE": "CUSTOM-LICENSE" },
  "ignore": ["*.tmp"]
}

// No override file - uses defaultGroups from manifest
// (no .standards.override.json file)

This allows repositories to use override files for remap and ignore functionality without needing to explicitly specify groups if the default groups are appropriate.

Advanced ignore patterns

The ignore array supports powerful wildcard patterns for flexible file exclusion:

{
  "schema": "2",
  "groups": ["core", "docs"],
  "ignore": [
    "*.tmp",                    // All temporary files
    "*.bak",                    // All backup files
    "temp/*",                   // Everything in temp folder
    "draft/*",                  // Everything in draft folder
    "*debug*",                  // Any file containing "debug"
    "test-*.json",              // Files like test-manifest.json, test-config.json
    "draft?.md",                // Files like draft1.md, drafta.md (single char)
    "v[0-9].*",                 // Version files like v1.json, v2.txt
    "assets/temp/**",           // All temporary assets
    "tools/backup/**",          // All backup tools
    "**/temp/**",               // All temp folders anywhere in the tree
    "**/*.draft",               // All .draft files anywhere
    "*.old",                    // Old versions of files
    "backup-*",                 // Files starting with "backup-"
    "experimental/*"            // Everything in experimental folder
  ]
}

Pattern matching rules:

Patterns are case-insensitive on Windows, case-sensitive on Linux/macOS
Use forward slashes / for path separators (works on all platforms)
** matches any number of directories (recursive)
Patterns match against the destination path (dst) from the manifest

Groups feature

The groups feature allows different types of repositories to receive different sets of files, making the synchronization system more flexible and reducing unnecessary files in specific repository types.

Use cases

Core libraries (group: ["core"]):

License, NuGet icon, sync tools

Add-on repositories (group: ["core", "add-on"]):

License, NuGet icon, sync tools
Standardized add-on asset generation scripts
Unified NuGet generation and helper scripts

Binding repositories (group: ["core", "binding"]):

License, NuGet icon, sync tools
Standardized binding generation scripts

Local testing

You can test the sync locally without CI:

# Test with remote source (default)
pwsh ./scripts/sync-standards.ps1 -DryRun

# Test with local source
pwsh ./scripts/sync-standards.ps1 -SourcePath "../evergine-standards" -DryRun

# Test with specific groups by creating a temporary override file
echo '{"schema":"2","groups":["core","docs"]}' > .standards.override.json
pwsh ./scripts/sync-standards.ps1 -SourcePath "../evergine-standards" -DryRun
rm .standards.override.json

# Test with ignore patterns
echo '{"schema":"2","ignore":["*.tmp","temp/*","*debug*"]}' > .standards.override.json
pwsh ./scripts/sync-standards.ps1 -SourcePath "../evergine-standards" -DryRun
rm .standards.override.json

This simulates the synchronization and shows which files would be processed without making actual changes.

Summary

Component	Role
`sync-manifest.json`	Defines which files are synchronized using schema v2 with groups
`scripts/sync-standards.ps1`	Performs synchronization (PowerShell) with schema v2 support
`_sync-standards-reusable.yml`	Core reusable workflow with dynamic script download
`sync-standards.yml`	Template workflow copied to each repo
`.standards.override.json`	Per-repo customization (groups, remap, ignore)

Groups benefits:

Flexible targeting: Different repository types get appropriate file sets
Reduced clutter: Repositories only receive relevant files
Scalable maintenance: New file types can be added to specific groups
Clean separation: Logical organization of files by purpose (core vs docs vs ci vs build)

Maintainers:
This repository should remain minimal and versioned carefully — avoid including secrets, credentials, or environment-specific files.

Development and Versioning Workflow

How to create a new version branch (`v2`, `v3`, ...)

Update internal uses: references:

On the main branch, replace all @main with @v2 (or the appropriate version) in all uses: fields for actions and reusable workflows.

Create the version branch:

Before committing, create the new branch:

git checkout -b v2
git add .
git commit -m "Update internal uses to @v2 for stable release"
git push origin v2

(Optional) Revert changes in main:

If you want main to keep using @main for development, switch back to main and discard the changes.

Hotfixes:

Apply hotfixes directly to the version branch (v2). If needed, you can merge them back into main later.

How should consumer repositories reference this repo?

For maximum stability:
- Consumer repositories should always use the stable branch/tag in their uses::
```
uses: EvergineTeam/evergine-standards/.github/workflows/addon-simple-cd.yml@v2
```
For development or testing:
- Only in special cases should you point to @main or a feature branch. This is not recommended for production.

Why use `v2`, `v3`, ... branches/tags?

This is the standard convention for GitHub Actions.
It allows you to introduce breaking changes in main without affecting consumers.
Consumers can migrate to new versions when they choose.

Tip: Before creating the version branch, you can use a script or search to update all @main to @v2 in workflows and actions.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github		.github
assets		assets
scripts		scripts
tests		tests
workflows		workflows
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
sync-manifest.json		sync-manifest.json

Folders and files

Latest commit

History

Repository files navigation

Workflow update automation limitation

Evergine standards

Overview

Repository structure

Generate-Assets-AddOn.ps1

Usage

Parameters

Example

Binding repositories support

Generate-Bindings-DotNet.ps1

Usage

Parameters

Example

Generate-NuGets-DotNet.ps1

Usage

Parameters

Example

Note on runner selection in reusable workflows

Example usage

Composite action for add-on asset generation

Composite action for NuGet generation

Composite action for email notifications

Composite action for commit/push/PR automation (XML update)

Reusable workflow for add-on CI

Reusable workflow for binding CI

Synchronization and reuse in native binding repositories

Synchronization workflow

1. Reusable workflow (centralized)

2. Wrapper workflow (per repository)

Parameters for the reusable workflow

Synchronization script (scripts/sync-standards.ps1)

Local override option

Using the download helper

Manual setup

Important considerations

Usage

Download helper (scripts/download-sync-script.ps1)

Usage

Parameters

Examples

Manifest format (sync-manifest.json)

Overrides (.standards.override.json)

Group selection examples

Group selection behavior

Advanced ignore patterns

Groups feature

Use cases

Local testing

Summary

Development and Versioning Workflow

How to create a new version branch (v2, v3, ...)

How should consumer repositories reference this repo?

Why use v2, v3, ... branches/tags?

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Contributors

Uh oh!

Languages

Synchronization script (`scripts/sync-standards.ps1`)

Download helper (`scripts/download-sync-script.ps1`)

Manifest format (`sync-manifest.json`)

Overrides (`.standards.override.json`)

How to create a new version branch (`v2`, `v3`, ...)

Why use `v2`, `v3`, ... branches/tags?