@oorabona/release-it-preset 0.8.0 → 0.8.1

package/README.md

@@ -564,16 +564,16 @@ pnpm release
 
 ## Configuration Modes
 
-The preset supports three configuration modes to suit different workflows:
+The preset supports two configuration modes:
 
-### Mode 1: CLI Only (No Config File)
+### Mode 1: Direct Preset Usage (No Config File)
 
-**When to use:** Simple projects with minimal customization needs
+**When to use:** Simple projects, trust preset defaults, or customize only via environment variables
 
 Don't create `.release-it.json`. Just run the CLI:
 
 ```bash
-pnpm release-it-preset hotfix
+pnpm release-it-preset default
 ```
 
 All configuration comes from the preset and environment variables.
@@ -582,23 +582,22 @@ All configuration comes from the preset and environment variables.
 - ✅ Zero config files
 - ✅ Consistent behavior across projects
 - ✅ Easy to understand
+- ✅ Perfect for getting started
 
 ---
 
-### Mode 2: CLI + User Overrides (Recommended)
+### Mode 2: Preset + User Overrides (Recommended)
 
-**When to use:** Customize specific options while using CLI presets
+**When to use:** Customize specific options while keeping preset defaults
 
-Create `.release-it.json` **WITHOUT the `extends` field**:
+Create `.release-it.json` **WITH the `extends` field**:
 
 ```json
 {
+  "extends": "@oorabona/release-it-preset/config/default",
   "git": {
     "requireBranch": "master",
     "commitMessage": "chore: release v${version}"
-  },
-  "npm": {
-    "publish": true
   }
 }
 ```
@@ -606,24 +605,26 @@ Create `.release-it.json` **WITHOUT the `extends` field**:
 Run with CLI preset:
 
 ```bash
-pnpm release-it-preset hotfix
+pnpm release-it-preset default
 ```
 
 **How it works:**
-- CLI selects the preset (`hotfix` in this example)
-- release-it merges your overrides on top of the preset
+- The `extends` field loads the preset
+- release-it merges your overrides on top via c12
 - **Your values take precedence** over preset defaults
+- CLI validates that `extends` matches the command
 
 **Pros:**
-- ✅ **Recommended approach** for most use cases
-- ✅ CLI controls preset selection
-- ✅ Declarative overrides in config file
-- ✅ No `extends` maintenance needed
+- ✅ **Recommended for customization**
+- ✅ Declarative config with explicit preset
+- ✅ Industry standard pattern (like ESLint, TypeScript)
+- ✅ Guaranteed config merging via release-it's c12
 
-**Example use case:** You want to use the `hotfix` preset but require releases from `master` instead of `main`:
+**Example:** Using `hotfix` preset but release from `master` instead of `main`:
 
 ```json
 {
+  "extends": "@oorabona/release-it-preset/config/hotfix",
   "git": {
     "requireBranch": "master"
   }
@@ -631,84 +632,73 @@ pnpm release-it-preset hotfix
 ```
 
 ```bash
-pnpm release-it-preset hotfix  # Uses hotfix preset + your branch override
+pnpm release-it-preset hotfix
 ```
 
 ---
 
-### Mode 3: File with Extends (Advanced)
+### Configuration Validation
 
-**When to use:** Lock a specific preset regardless of CLI command
+The CLI validates your `.release-it.json` to prevent misconfigurations:
 
-Create `.release-it.json` **WITH the `extends` field**:
+#### Error 1: Missing `extends` field
 
-```json
+```bash
+# .release-it.json without extends:
 {
-  "extends": "@oorabona/release-it-preset/config/hotfix",
-  "git": {
-    "commitMessage": "custom: ${version}"
-  }
+  "git": { "requireBranch": "master" }
 }
-```
 
-Run matching CLI command:
+# Running:
+pnpm release-it-preset default
 
-```bash
-pnpm release-it-preset hotfix  # Must match the extends!
+# ❌ Configuration error!
+#    .release-it.json is missing the required "extends" field.
+#
+#    Without "extends", your config won't merge with the preset.
+#    This means you'll get release-it defaults instead of preset defaults.
+#
+#    Fix by adding this to .release-it.json:
+#      {
+#        "extends": "@oorabona/release-it-preset/config/default",
+#        ...your overrides
+#      }
 ```
 
-**How it works:**
-- The `extends` field locks the preset
-- CLI command **must match** the preset in `extends`
-- Mismatch triggers an error
-
-**Pros:**
-- ✅ Prevents accidental use of wrong presets
-- ✅ Explicit preset declaration in config
-
-**Cons:**
-- ⚠️ Less flexible (preset locked in file)
-- ⚠️ Requires updating `extends` to switch presets
-
----
-
-### Configuration Error Handling
+**Why `extends` is required:** Without it, release-it only loads your config file and uses release-it's own defaults. The preset is never loaded, so you lose important defaults like `npm.publish: false`.
 
-If your `.release-it.json` has an `extends` field that doesn't match the CLI command, you'll get a clear error:
+#### Error 2: Preset mismatch
 
 ```bash
-# Your config extends "default", but you run:
+# .release-it.json extends "default":
+{
+  "extends": "@oorabona/release-it-preset/config/default"
+}
+
+# But you run:
 pnpm release-it-preset hotfix
 
 # ❌ Configuration mismatch error!
 #    CLI preset:               hotfix
 #    .release-it.json extends: default
 #
-# Either:
-#   1. Remove the "extends" field from .release-it.json (recommended)
-#      → Your overrides will merge with the CLI preset automatically
-#
-#   2. Run: release-it-preset default
-#      → Use the preset specified in your config file
-#
-#   3. Update .release-it.json extends to: "@oorabona/release-it-preset/config/hotfix"
-#      → Match your config file to the CLI command
+#    Either:
+#      1. Run: release-it-preset default
+#      2. Update .release-it.json extends to: "@oorabona/release-it-preset/config/hotfix"
 ```
 
-This prevents silent misconfigurations where the wrong preset runs unexpectedly.
-
 ---
 
 ### Which Mode Should I Use?
 
 | Scenario | Recommended Mode |
 |----------|------------------|
-| Minimal config, trust defaults | **Mode 1** (CLI only) |
-| Customize branch/commit messages | **Mode 2** (CLI + overrides) |
-| Lock preset for safety | **Mode 3** (File with extends) |
-| Monorepo with different presets per package | **Mode 2** (CLI + overrides) |
+| Quick start, minimal config | **Mode 1** (No config file) |
+| Customize branch/commit/hooks | **Mode 2** (Config with extends) |
+| Environment-only customization | **Mode 1** (Use env vars) |
+| Monorepo with per-package config | **Mode 2** (Each package has own config) |
 
-**Most users should use Mode 2** for the best balance of flexibility and clarity.
+**Use Mode 1 to get started, switch to Mode 2 when you need customization.**
 
 ## Borrowing Scripts & Workflows
 

package/bin/cli.js

@@ -119,36 +119,44 @@ function handleReleaseCommand(configName, args) {
 
       const expectedExtends = `@oorabona/release-it-preset/config/${configName}`;
 
-      if (userConfig.extends) {
-        // If extends exists, it MUST match the CLI preset
-        const extendsMatch = userConfig.extends.match(/@oorabona\/release-it-preset\/config\/(\w+)/);
-        const extendsPreset = extendsMatch?.[1];
-
-        if (extendsPreset && extendsPreset !== configName) {
-          console.error(`\n❌ Configuration mismatch error!`);
-          console.error(`   CLI preset:               ${configName}`);
-          console.error(`   .release-it.json extends: ${extendsPreset}`);
-          console.error(``);
-          console.error(`Either:`);
-          console.error(`  1. Remove the "extends" field from .release-it.json (recommended)`);
-          console.error(`     → Your overrides will merge with the CLI preset automatically`);
-          console.error(``);
-          console.error(`  2. Run: release-it-preset ${extendsPreset}`);
-          console.error(`     → Use the preset specified in your config file`);
-          console.error(``);
-          console.error(`  3. Update .release-it.json extends to: "${expectedExtends}"`);
-          console.error(`     → Match your config file to the CLI command\n`);
-          process.exit(1);
-        }
-
-        console.log(`✅ Config file extends matches CLI preset: ${configName}`);
-        console.log(`📝 Using: ${userConfigPath}\n`);
-      } else {
-        // No extends = natural merge (Mode 3 - Hybrid)
-        console.log(`📝 Merging CLI preset "${configName}" with user config overrides`);
-        console.log(`   Config file: ${userConfigPath}`);
-        console.log(`   User overrides will take precedence\n`);
+      if (!userConfig.extends) {
+        // ERROR: extends is required for config merging
+        console.error(`\n❌ Configuration error!`);
+        console.error(`   .release-it.json is missing the required "extends" field.`);
+        console.error(``);
+        console.error(`Without "extends", your config won't merge with the preset.`);
+        console.error(`This means you'll get release-it defaults instead of preset defaults.`);
+        console.error(``);
+        console.error(`Fix by adding this to .release-it.json:`);
+        console.error(`  {`);
+        console.error(`    "extends": "${expectedExtends}",`);
+        console.error(`    ...your overrides`);
+        console.error(`  }`);
+        console.error(``);
+        console.error(`Or remove .release-it.json to use the preset directly.\n`);
+        process.exit(1);
+      }
+
+      // Validate extends matches CLI preset
+      const extendsMatch = userConfig.extends.match(/@oorabona\/release-it-preset\/config\/(\w+)/);
+      const extendsPreset = extendsMatch?.[1];
+
+      if (extendsPreset && extendsPreset !== configName) {
+        console.error(`\n❌ Configuration mismatch error!`);
+        console.error(`   CLI preset:               ${configName}`);
+        console.error(`   .release-it.json extends: ${extendsPreset}`);
+        console.error(``);
+        console.error(`Either:`);
+        console.error(`  1. Run: release-it-preset ${extendsPreset}`);
+        console.error(`     → Use the preset specified in your config file`);
+        console.error(``);
+        console.error(`  2. Update .release-it.json extends to: "${expectedExtends}"`);
+        console.error(`     → Match your config file to the CLI command\n`);
+        process.exit(1);
       }
+
+      console.log(`✅ Config validated: preset "${configName}"`);
+      console.log(`📝 Using: ${userConfigPath}\n`);
     } catch (error) {
       if (error instanceof SyntaxError) {
         console.error(`❌ Failed to parse .release-it.json: ${error.message}`);
@@ -158,12 +166,12 @@ function handleReleaseCommand(configName, args) {
       process.exit(1);
     }
 
-    // Let release-it handle the merge naturally
+    // Let release-it discover .release-it.json and merge via extends
     fullArgs = [...args];
   } else {
     // No user config - use preset directly
     console.log(`📝 Using preset config directly: ${configPath}`);
-    console.log(`   Tip: Create .release-it.json (without "extends") to add overrides\n`);
+    console.log(`   Tip: Create .release-it.json with "extends" to customize\n`);
     fullArgs = ['--config', configPath, ...args];
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oorabona/release-it-preset",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Shared release-it configuration and scripts for the organisation",
   "type": "module",
   "keywords": [