Refguide Package management foundation

content/en/docs/refguide/modeling/app-explorer/modules/module-settings.md

@@ -25,6 +25,10 @@ Select the **Export** tab:
 
 {{< figure src="/attachments/refguide/modeling/app-explorer/modules/module-settings/module-settings-export.png" class="no-border" >}}
 
+## Configure
+
+Configure section contains basic settings of the module.
+
 ### Module Type {#module-type}
 
 There are three types of modules, and the choice of type depends on the purpose of the module. You can choose one the following:
@@ -62,16 +66,79 @@ When the module is set as the solution module, it gets the letter **S** as an ic
 ### Module Version
 
 {{% alert color="info" %}}
-This setting is available only for add-on and solution module types.
-{{% /alert %}}
+From Studio Pro 11.12 and above version is available for all module types. For earlier versions of Studio Pro version is available only for Add-on and Solution module types. 
+{{% /alert %}}  
 
 This is the version number of the module. The version should be a semantic version (meaning, it should consist of at least three parts: major, minor, and patch version). For more information on semantic versions, see [Semantic Versioning](https://semver.org/).
 
 Mendix recommends setting a new version every time changes are made to the module.
 
+## Package {#package}
+
+{{% alert color="info" %}}
+This section is available from Studio Pro 11.12 and above.
+{{% /alert %}}
+
+Studio Pro 11.12 introduces improved package management to enable reliable module tracking and updates.
+
+For more information on how to use package management when updating modules, see [Updating Marketplace Modules](https://github.com/mendix/docs/blob/development/refguide/updating-marketplace-modules).
+
+The key improvements are delivered through new module properties and a new `manifest.json` file format in module packages (*.mpk* files):
+
+- **Package identification** – Each module receives a Module ID that uniquely identifies it throughout all versions. This allows Studio Pro to reliably track modules across updates, even if the module name changes.
+- **Package integrity** – Each package includes a checksum (SHA-256 hash) that is used to verify the integrity of the package itself and of the imported module in the App.
+- **Metadata tracking** – The manifest includes information about the package name, version (following semantic versioning), type, and the Mendix metamodel version used to create it.
+
+The **Package** section on the **General** tab shows package identification information for the module. Studio Pro uses this information to track modules across versions, which is the foundation for more reliable module updates.
+
+### Module ID {#module-id}
+
+The **Module ID** is a unique identifier for the module that stays the same across all versions of the module. It is used to determine whether two module packages represent the same module, and is therefore the basis for module update compatibility: if two modules share the same Module ID, Studio Pro can update one with the other; if the IDs differ, Studio Pro treats them as distinct modules.
+
+#### Automatic Module ID Assignment
+
+The Module ID is assigned automatically and is stable across devices, so multiple developers working on the same module independently end up with the same value:
+
+* For a module imported from the Marketplace, the Module ID is derived from the Marketplace component ID.
+* For any other module, the Module ID is derived from the App ID and the module name. This ensures the ID remains consistent across devices when multiple developers work independently.
+
+When you open an existing app in Studio Pro 11.12 or above, every module that does not yet have a Module ID receives one automatically. No action is required from you.
+
+#### Manual Module ID override
+
+In some cases you might want to override the automatically assigned Module ID. To change it, click the pencil icon next to it. A dialog opens where you can enter a new value.
+
+{{% alert color="warning" %}}
+Changing the Module ID may break existing installations that depend on this module. Only override this value if you know what you are doing.
+{{% /alert %}}
+
+### Checksum {#checksum}
+
+The **Checksum** is a read-only SHA-256 hash that uniquely identifies a specific version of the module package. It serves two purposes:
+
+* **Integrity** – This checksum is a hash of the contents of the original module package that StudioPro can use to detect if there were any user modifications after the module was imported.
+* **Version identification** – Lets you compare two module packages for equality without inspecting their contents.
+
+The checksum is shown only for modules that were imported from a module package. For modules created directly in your app, the checksum is calculated when you export the module and is not displayed in the **Package** section.
+
+### Package Manifest {#package-manifest}
+
+When you export a module package (an *.mpk* file), Studio Pro 11.12 and above adds a `manifest.json` file to the package alongside the existing metadata. The manifest contains:
+
+* The Module ID and Module name
+* The Module version
+* The Checksum of the package
+* The Mendix metamodel version used to create the package
+* The list of files included in the package
+
+The legacy `package.xml` metadata file is still included for backward compatibility.
+
+
+
 ## Read More
 
 * [Modules](/refguide/modules/)
+* [Update modules](refguide/updating-marketplace-modules)
 * [Configure Add-on and Solution Modules for Publishing](/refguide/configure-add-on-and-solution-modules/)
 * [Applying Intellectual Property Protection](/appstore/creating-content/sol-ip-protection/)
 * [Creating Solutions](/appstore/creating-content/sol-solutions-guide/)

content/en/docs/refguide/modeling/app-explorer/modules/updating-marketplace-modules.md

@@ -0,0 +1,46 @@
+---
+title: "Updating Marketplace Modules"
+url: /refguide/updating-marketplace-modules/
+weight: 40
+description: "Describes how to update Marketplace modules while retaining your customizations using three-way merge."
+---
+
+## Introduction
+
+Previously, when you wanted to update a Marketplace module to a newer version, you had to fully replace the module. This meant losing any customizations you had made, such as modified microflows or added functionality. If you had customized a module, you had to choose between keeping your changes or getting the latest updates from the publisher.
+
+Studio Pro 11.12 changes this by enabling module updates that retain your customizations. Now, when you update a module, Studio Pro performs a three-way merge that intelligently combines your customizations with the publisher's updates. This means you can both keep your changes and benefit from bug fixes and new features in the updated module.
+
+{{% alert color="info" %}}
+Studio Pro 11.12 introduces improved package management with package IDs and document GUID mappings that make updates more reliable. However, updates with customization retention also work for older modules without package IDs through name-based mapping. For more information on package management, see [Module Settings](/refguide/module-settings/#package).
+{{% /alert %}}
+
+## Updating Modules with Three-Way Merge
+
+### Three-Way Merge Process
+
+To retain your customizations when updating a module, Studio Pro performs a three-way merge. This process requires three versions:
+
+1. **Original version** – The version of the Marketplace module that you originally imported
+2. **Current version** – The version currently in your app, which may include your modifications
+3. **Target version** – The new version of the Marketplace module that you want to upgrade to
+
+You must manually provide both the original and target versions. If the mapping of documents succeeds, the merge begins. If mapping fails, you cannot upgrade while keeping your customizations, and you must fully overwrite the module.
+
+During the merge, conflicts may occur if you and the publisher both modified the same element (for example, the same microflow). For information on resolving conflicts, see [Combining Changes and Resolving Conflicts](/refguide/resolving-conflicts/).
+
+### Document Mapping
+
+To successfully merge your customizations with the updated module, Studio Pro needs to match documents between the old and new versions. The method Studio Pro uses depends on whether the module has package identification:
+
+* **Modules with package IDs** – Studio Pro uses the embedded GUID mapping information to match documents by GUID. This is more reliable because documents can be matched even if they have been renamed.
+* **Modules without package IDs** – Studio Pro attempts to map documents by name. This works well as long as document names have not changed between versions.
+
+For more information on package IDs and how they are assigned, see [Module Settings](/refguide/module-settings/#package).
+
+## Read More
+
+* [Modules](/refguide/modules/)
+* [Module Settings](/refguide/module-settings/)
+* [Consuming Add-on Modules and Solutions](/refguide/consume-add-on-modules-and-solutions/)
+* [Combining Changes and Resolving Conflicts](/refguide/resolving-conflicts/)