@@ -74,3 +74,69 @@ It will:
7474* bump version is source files automatically,
7575* commit changes,
7676* push release tag that will initiate [ release workflow] ( .github/workflows/release-perform.yml ) .
77+
78+ # Coding Conventions
79+
80+ ## File Naming
81+
82+ | Pattern | Purpose | Example |
83+ | ---------| ---------| --------|
84+ | ` local_*.go ` | Local instance-specific functionality | ` local_instance.go ` , ` local_instance_manager.go ` |
85+ | ` *_manager.go ` | Manager classes handling collections/operations | ` package_manager.go ` , ` osgi_bundle_manager.go ` |
86+ | ` *_test.go ` | Unit tests | ` instance_test.go ` |
87+ | ` *_int_test.go ` | Integration tests (require running AEM) | ` osgi_int_test.go ` |
88+
89+ ## Architectural Patterns
90+
91+ ### Manager Hierarchy
92+
93+ Three types of managers exist:
94+
95+ 1 . ** AEM-level** - owned by ` AEM ` facade, operate globally (` VendorManager ` , ` ContentManager ` )
96+ 2 . ** Instance-level** - owned by ` Instance ` , operate via HTTP (` PackageManager ` , ` OSGiBundleManager ` )
97+ 3 . ** Sub-entity** - owned by facade types (` OSGi ` owns ` BundleManager ` , ` ConfigManager ` , etc.)
98+
99+ ### Entity + EntityState
100+
101+ Domain entities have paired ` *State ` structs for serialization:
102+
103+ ``` go
104+ type OSGiBundle struct { manager *OSGiBundleManager; symbolicName string }
105+ type OSGiBundleState struct { SymbolicName string ` yaml:"symbolic_name"`
106+ ```
107+
108+ ### WithChanged Pattern
109+
110+ Methods returning ` (bool, error) ` indicate if change was made (for idempotent operations):
111+
112+ ``` go
113+ func (b OSGiBundle ) Start () error { ... } // Always attempts
114+ func (b OSGiBundle ) StartWithChanged () (bool , error ) // Returns false if already started
115+ ```
116+
117+ ### Facade Pattern
118+
119+ `OSGi`, `Sling`, `Repo`, `Auth` group related managers:
120+
121+ ```go
122+ type OSGi struct {
123+ bundleManager *OSGiBundleManager
124+ componentManager *OSGiComponentManager
125+ configManager *OSGiConfigManager
126+ }
127+ ```
128+
129+ ## Utility Packages
130+
131+ Packages in ` pkg/common/ ` use ` *x ` suffix for extended stdlib functionality:
132+
133+ ` pathx ` , ` fmtx ` , ` httpx ` , ` stringsx ` , ` timex ` , ` osx ` , ` filex ` , ` cryptox ` , ` execx ` , ` tplx ` , ` netx `
134+
135+ ## Sub-packages
136+
137+ ` pkg/{domain}/ ` contains pure data types without AEM dependencies:
138+
139+ - ` pkg/osgi/ ` - OSGi data structures
140+ - ` pkg/instance/ ` - Instance constants and utilities
141+ - ` pkg/content/ ` - Content manipulation
142+ - ` pkg/keystore/ ` - Keystore types
0 commit comments