sf-plugin-permission-sets 0.0.0-dev.18 → 0.0.0-dev.20

package/README.md

@@ -1,10 +1,12 @@
 # sf-plugin-permission-sets
 
-[![NPM](https://img.shields.io/npm/v/sf-plugin-permission-sets.svg?label=sf-plugin-permission-sets)](https://www.npmjs.com/package/sf-plugin-permission-sets) [![Downloads/week](https://img.shields.io/npm/dw/sf-plugin-permission-sets.svg)](https://npmjs.org/package/sf-plugin-permission-sets) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/zaclummys/sf-plugin-permission-sets/main/LICENSE.txt)
+[![NPM](https://img.shields.io/npm/v/sf-plugin-permission-sets.svg?label=sf-plugin-permission-sets)](https://www.npmjs.com/package/sf-plugin-permission-sets) [![Downloads/week](https://img.shields.io/npm/dw/sf-plugin-permission-sets.svg)](https://npmjs.org/package/sf-plugin-permission-sets) [![Stability: experimental](https://img.shields.io/badge/stability-experimental-orange.svg)](https://semver.org/#spec-item-4) [![License](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://raw.githubusercontent.com/zaclummys/sf-plugin-permission-sets/main/LICENSE.txt)
 
 > Declarative, GitOps-style management of **permission set assignments** for Salesforce orgs.
 > Define who gets what in version-controlled YAML. The plugin reconciles your org to match it: `plan` then `apply`, just like Terraform.
 
+> ⚠️ **Under active development.** This plugin is `0.x`. Per [semver's major-version-zero rule](https://semver.org/#spec-item-4), anything (commands, flags, the YAML schema) may change in a breaking way between `0.x` releases. Pin a version in CI. The public API stabilizes at `v1.0.0`.
+
 Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let CI show the diff, and merge to apply. Your git history becomes the audit log of who-had-access-when.
 
 ---
@@ -16,8 +18,8 @@ Stop clicking through Setup to grant access. Commit a YAML file, open a PR, let
 - [Quick start](#quick-start)
 - [Permission files](#permission-files)
 - [Organizing files](#organizing-files)
-- [Validations](#validations)
 - [Modes](#modes)
+- [Validations](#validations)
 - [Commands](#commands)
 - [Inspiration & equivalents](#inspiration--equivalents)
 - [Versioning](#versioning)
@@ -157,18 +159,6 @@ sf ps apply -o qa   --file "permissions/qa/*.yml"
 
 The two compose: a directory per environment, each split into functional files.
 
-## Validations
-
-Every run checks the files first. `check` runs the offline checks with no org, and `validate` adds the org-side checks. When files merge, most overlaps are unions rather than errors.
-
-| Situation | Checked by | Severity | Result |
-| --- | --- | :---: | --- |
-| Same username key appears twice in one file | `check` (offline) | ❌ error | Rejected, the intent is ambiguous |
-| Same target listed twice for a user | `check` (offline) | ⚠️ warning | Deduped |
-| A user with no scopes, or an empty list | `check` (offline) | ⚠️ warning | Ignored as a no-op |
-| Same user in two files with different targets | `check` (offline) | ✅ ok | Merged into one model, the point of slicing |
-| Declared user, permission set, group, or license missing or not unique | `validate` (online) | ❌ error | Run fails before any change |
-
 ## Modes
 
 A run performs two atomic operations: **add** missing assignments and **remove** undeclared ones. The mode selects which it actually executes. Set it with `--mode` (default `additive`):
@@ -181,6 +171,18 @@ A run performs two atomic operations: **add** missing assignments and **remove**
 
 `plan` always shows the *full* picture (both adds **and** would-be removes) regardless of mode, so you can preview the impact before running it. Whatever the chosen mode won't act on is surfaced as **drift**. Gate CI on it with `--fail-on-drift`.
 
+## Validations
+
+Every run checks the files first. `check` runs the offline checks with no org, and `validate` adds the org-side checks. When files merge, most overlaps are unions rather than errors.
+
+| Situation | Checked by | Severity | Result |
+| --- | --- | :---: | --- |
+| Same username key appears twice in one file | `check` (offline) | ❌ error | Rejected, the intent is ambiguous |
+| Same target listed twice for a user | `check` (offline) | ⚠️ warning | Deduped |
+| A user with no scopes, or an empty list | `check` (offline) | ⚠️ warning | Ignored as a no-op |
+| Same user in two files with different targets | `check` (offline) | ✅ ok | Merged into one model, the point of slicing |
+| Declared user, permission set, group, or license missing or not unique | `validate` (online) | ❌ error | Run fails before any change |
+
 ## Commands
 
 | Command          | Purpose                                                                 |
@@ -321,6 +323,8 @@ Releases follow [semantic versioning](https://semver.org). Snapshots are automat
 - Choosing the version bump (patch, minor, or major).
 - Creating the GitHub Release, which is what triggers the publish above.
 
+**While on `0.x`:** breaking changes may ship in **any** release, including minor bumps. The plugin is under active development and the public API is not yet stable. The table below describes the contract that takes effect at `v1.0.0`.
+
 | Bump | When | Example tag |
 | --- | --- | --- |
 | patch | bug fix, no behavior change | `v0.1.1` |

package/oclif.manifest.json

@@ -182,5 +182,5 @@
       ]
     }
   },
-  "version": "0.0.0-dev.18"
+  "version": "0.0.0-dev.20"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sf-plugin-permission-sets",
-    "description": "",
+    "description": "Declarative permission set assignment management for Salesforce. Under active development, with breaking changes possible until v1.0.0.",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/zaclummys/sf-plugin-permission-sets.git"
@@ -133,5 +133,5 @@
     "exports": "./lib/index.js",
     "type": "module",
     "author": "Isaac Ferreira",
-    "version": "0.0.0-dev.18"
+    "version": "0.0.0-dev.20"
 }