Maintaining This Package

How to contribute, version, and publish updates to the Pixel Engine Conventions package.

Commit Convention

This repo uses Conventional Commits. Your commit message determines the next version.

Prefix	Version Bump	Example
`feat:`	Minor (0.1.0 → 0.2.0)	`feat: add service locator pattern`
`fix:`	Patch (0.1.0 → 0.1.1)	`fix: correct naming table typo`
`feat!:` or `BREAKING CHANGE:`	Major (0.1.0 → 1.0.0)	`feat!: rename IState to IModuleState`
`docs:`	No release	`docs: update cheatsheet`
`chore:`	No release	`chore: update CI workflow`
`refactor:`	No release	`refactor: simplify module generator`

Release Flow

Everything is automated via GitHub Actions.

1. You push commits to main
2. release-please reads commit messages
3. Creates a "Release PR" with:
   - Updated CHANGELOG.md
   - Bumped version in package.json
4. You merge the Release PR
5. GitHub creates a Release + git tag
6. npm publish runs automatically
7. Users update via Package Manager

You never manually bump versions, write changelogs, or run npm publish.

Day-to-Day Workflow

Adding a New Convention Page

# 1. Create the markdown file
# 2. Add it to Documentation~/articles/toc.yml
# 3. Commit with docs: prefix (no release triggered)
git commit -m "docs: add error handling conventions page"
git push

Updating an Interface

# This is a breaking change — use feat!:
git commit -m "feat!: add Reset() method to IView interface"
git push
# release-please will create a major version bump PR

Fixing a Bug in the Editor Tools

git commit -m "fix: module generator missing IDisposable using"
git push
# release-please will create a patch version bump PR

Updating Documentation Only

git commit -m "docs: clarify readonly struct usage in module pattern"
git push
# No release created — docs-only commits don't trigger releases

Rebuilding the DocFX Site

cd Documentation~
docfx build
docfx serve _site -p 8080

The _site/ folder is gitignored. Build locally to preview, but don't commit it.

Adding the Package to a New Unity Project

Via npm Scoped Registry (Recommended)

Add to Packages/manifest.json:

{
  "scopedRegistries": [
    {
      "name": "npm",
      "url": "https://registry.npmjs.org",
      "scopes": ["com.pixelengine"]
    }
  ],
  "dependencies": {
    "com.pixelengine": "1.0.0"
  }
}

Via Git URL

{
  "dependencies": {
    "com.pixelengine": "https://github.com/savesyncgames-sudo/PixelEngine.git#v1.0.0"
  }
}

Secrets & Tokens

Secret	Where	Purpose
`NPM_TOKEN`	GitHub repo secrets	npm publish authentication
`GITHUB_TOKEN`	Auto-provided by Actions	release-please PR creation

To rotate the npm token:

Create a new token at https://www.npmjs.com/settings/pixelpunchgames/tokens
Update: gh secret set NPM_TOKEN --repo savesyncgames-sudo/PixelEngine

Repo Structure

PixelEngine/
├── .github/workflows/
│   └── release.yml          ← CI: release-please + npm publish
├── Runtime/
│   ├── Architecture/        ← Interfaces (IConfiguration, IState, etc.)
│   └── com.pixelengine.asmdef
├── Editor/
│   ├── ProjectSetupTool.cs  ← Pixel Engine/ menu items
│   ├── ModuleGenerator.cs   ← Code generation
│   └── com.pixelengine.editor.asmdef
├── Documentation~/          ← DocFX site (ignored by Unity)
├── package.json             ← UPM + npm manifest
├── CHANGELOG.md             ← Auto-generated by release-please
└── README.md

Table of Contents