Merge pull request #90 from amtrack/docs

docs: document plugin scope and profile behaviour

README.md

@@ -4,13 +4,10 @@
 
 For certain Metadata Types there is a different behaviour of the [file-based](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_retrieve.htm) vs. [CRUD-based](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/meta_readMetadata.htm) Metadata API.
 
-This plugin provides the `sf force source read` command to read Metadata using the "CRUD-based" Metadata API
-similar to `sf force source retrieve` (which uses the "file-based" Metadata API).
+This plugin provides a `sf force source read` command to read Metadata using the "CRUD-based" Metadata API similar to `sf force source retrieve` (which uses the "file-based" Metadata API).
 
-## Example
-
-- When retrieving a `Profile` using `sf force source retrieve` it only contains `<userPermissions>`.
-- When retrieving a `Profile` using `sf force source read` it contains all fields like `<fieldPermissions>`, `<tabVisibilities>` and more.
+> [!NOTE]
+> This plugin simply returns the unfiltered response from the CRUD-based Metadata API.
 
 ## Installation
 
@@ -27,6 +24,31 @@ sf force source read -m "RecordType:Account.Business"
 sf force source read -p force-app/main/default/objects/Account/recordTypes/Business.recordType-meta.xml
 ```
 
+## Example
+
+### Retrieving Profiles using the file-based Metadata API
+
+When retrieving Profiles, the file-based Metadata API [behaves differently for source-tracked and non source-tracked orgs](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_source_tracking_source_tracking_profiles.htm):
+
+> Without source tracking, retrieving profiles only returns some profile information
+
+a.k.a. a minimal Profile containing only `userPermissions` and entries for components listed in the `package.xml` of the retrieve request.
+
+> With source tracking, retrieving profiles returns profile information pertaining to anything else specified in the package.xml file plus any components getting tracked by source tracking
+
+a.k.a. a more kind of "full" Profile containing entries for all metadata having a `SourceMember` record in that org.
+
+### Reading Profiles using the CRUD Metadata API
+
+The CRUD Metadata API shows yet another behaviour:
+
+It returns a kind of "full" Profile independent of source tracking and even containing entries for metadata from Managed Packages etc.
+
+> [!WARNING]
+> Unfortunately Profiles might include `tabVisibilites` for tabs not available in the org (see [#66](https://github.com/amtrack/sfdx-plugin-source-read/issues/66)).
+>
+> Without further processing this will cause deployment errrors.
+
 ## Disclaimer
 
 Currently this has been tested only for `Profiles` and `RecordTypes`.