docs: add Strapi update strategy documentation

AliKdhim87 · AliKdhim87 · commit 5bee2d05bdfb · 2025-08-22T16:25:13.000+02:00
diff --git a/README.md b/README.md
@@ -181,6 +181,10 @@ STRAPI_PUBLIC_URL=http://0.0.0.0:1337
 
 Choose the option that best fits your workflow to start the server without Docker. Once the server is running, you can access the application from your browser.
 
+## Strapi Updates
+
+For detailed information about updating Strapi (currently v4.25.8), including migration steps, testing strategy, and troubleshooting, see the [Strapi Update Strategy](./STRAPI_UPDATE_STRATEGY.md) guide.
+
 ## FAQ
 
 ### I Have Issues with Building the Project or Starting the Server
diff --git a/STRAPI_UPDATE_STRATEGY.md b/STRAPI_UPDATE_STRATEGY.md
@@ -0,0 +1,89 @@
+# Strapi Update Strategy
+
+This document outlines the process for updating Strapi from the current version (v4.25.8) to newer versions.
+
+## Pre-Update Checklist
+
+### 1. Review Official Documentation
+
+- **Critical**: Check the [Strapi Migration Guide](https://docs-v4.strapi.io/dev-docs/migration-guides) for breaking changes
+- Review the [Strapi Changelog](https://github.com/strapi/strapi/releases) for all versions between current and target version
+- Pay special attention to any database migration requirements
+
+### 2. Plugin Version Alignment
+
+- Ensure all standard Strapi plugins match the target Strapi version
+- Update plugin versions in `package.json` to align with the new Strapi version
+- Check compatibility of custom plugins with the new version
+
+## Update Process
+
+### 3. Homepage Customization (patch-package)
+
+We currently override the Strapi homepage using patch-package. After each update:
+
+1. **Locate Homepage Files**: Navigate to `node_modules/@strapi/admin/dist/chunks/`
+2. **Find Homepage Chunks**: Look for homepage-related files (may be multiple files for different locales)
+   - File names may change between versions
+   - Search for files containing homepage components
+3. **Apply Customizations**: Modify the homepage files as needed
+4. **Update Patch File**:
+
+   ```bash
+   # Remove old patch file
+   rm patches/@strapi+admin+*.patch
+
+   # Generate new patch file
+   npx patch-package @strapi/admin
+   ```
+
+### 4. React Version Compatibility
+
+If Strapi requires React updates:
+
+- Test the Strapi dashboard thoroughly
+- Pay special attention to non-standard Strapi plugins
+- Verify compatibility with custom-developed plugins
+
+## Testing Strategy
+
+### Core Testing
+
+- [ ] Content Manager (create, edit, delete, publish)
+- [ ] Media Library upload and management
+- [ ] Users & Permissions and admin authentication
+- [ ] API endpoints and GraphQL schema
+- [ ] Frontend data fetching and authentication flows
+
+### Plugin Testing
+
+- [ ] strapi-plugin-config-sync
+- [ ] `@frameless/strapi-plugin-uniform-product-name`
+- [ ] `@frameless/strapi-tiptap-editor`
+- [ ] Custom field types and validation
+- [ ] All other installed plugins
+
+## Post-Update Verification
+
+- [ ] Local and Docker environments (dev/prod)
+- [ ] All project variants (PDC, VTH)
+- [ ] Database migrations completed
+- [ ] Configuration and environment variables valid
+
+## Rollback Plan
+
+If issues are discovered:
+
+1. Revert to previous Strapi version in `package.json`
+2. Restore previous patch files from version control
+3. Run `yarn install` to reinstall previous versions
+4. Test functionality to ensure rollback success
+
+## Documentation Updates
+
+After successful update:
+
+- [ ] Update version numbers in documentation
+- [ ] Update any version-specific instructions
+- [ ] Document any new configuration requirements
+- [ ] Update environment variable documentation if needed
diff --git a/apps/strapi.frameless.io/docs/developers/STRAPI_UPDATE_STRATEGY.md b/apps/strapi.frameless.io/docs/developers/STRAPI_UPDATE_STRATEGY.md
@@ -0,0 +1,89 @@
+# Strapi Update Strategy
+
+This document outlines the process for updating Strapi from the current version (v4.25.8) to newer versions.
+
+## Pre-Update Checklist
+
+### 1. Review Official Documentation
+
+- **Critical**: Check the [Strapi Migration Guide](https://docs-v4.strapi.io/dev-docs/migration-guides) for breaking changes
+- Review the [Strapi Changelog](https://github.com/strapi/strapi/releases) for all versions between current and target version
+- Pay special attention to any database migration requirements
+
+### 2. Plugin Version Alignment
+
+- Ensure all standard Strapi plugins match the target Strapi version
+- Update plugin versions in `package.json` to align with the new Strapi version
+- Check compatibility of custom plugins with the new version
+
+## Update Process
+
+### 3. Homepage Customization (patch-package)
+
+We currently override the Strapi homepage using patch-package. After each update:
+
+1. **Locate Homepage Files**: Navigate to `node_modules/@strapi/admin/dist/chunks/`
+2. **Find Homepage Chunks**: Look for homepage-related files (may be multiple files for different locales)
+   - File names may change between versions
+   - Search for files containing homepage components
+3. **Apply Customizations**: Modify the homepage files as needed
+4. **Update Patch File**:
+
+   ```bash
+   # Remove old patch file
+   rm patches/@strapi+admin+*.patch
+
+   # Generate new patch file
+   npx patch-package @strapi/admin
+   ```
+
+### 4. React Version Compatibility
+
+If Strapi requires React updates:
+
+- Test the Strapi dashboard thoroughly
+- Pay special attention to non-standard Strapi plugins
+- Verify compatibility with custom-developed plugins
+
+## Testing Strategy
+
+### Core Testing
+
+- [ ] Content Manager (create, edit, delete, publish)
+- [ ] Media Library upload and management
+- [ ] Users & Permissions and admin authentication
+- [ ] API endpoints and GraphQL schema
+- [ ] Frontend data fetching and authentication flows
+
+### Plugin Testing
+
+- [ ] strapi-plugin-config-sync
+- [ ] `@frameless/strapi-plugin-uniform-product-name`
+- [ ] `@frameless/strapi-tiptap-editor`
+- [ ] Custom field types and validation
+- [ ] All other installed plugins
+
+## Post-Update Verification
+
+- [ ] Local and Docker environments (dev/prod)
+- [ ] All project variants (PDC, VTH)
+- [ ] Database migrations completed
+- [ ] Configuration and environment variables valid
+
+## Rollback Plan
+
+If issues are discovered:
+
+1. Revert to previous Strapi version in `package.json`
+2. Restore previous patch files from version control
+3. Run `yarn install` to reinstall previous versions
+4. Test functionality to ensure rollback success
+
+## Documentation Updates
+
+After successful update:
+
+- [ ] Update version numbers in documentation
+- [ ] Update any version-specific instructions
+- [ ] Document any new configuration requirements
+- [ ] Update environment variable documentation if needed
diff --git a/apps/strapi.frameless.io/docs/developers/readme.md b/apps/strapi.frameless.io/docs/developers/readme.md
@@ -238,6 +238,10 @@ TRANSFER_TOKEN_SALT=
 
 Choose the option that best fits your workflow to start the server without Docker. Once the server is running, you can access the application from your browser.
 
+## Strapi Updates
+
+For detailed information about updating Strapi (currently v4.25.8), including migration steps, testing strategy, and troubleshooting, see the [Strapi Update Strategy](./STRAPI_UPDATE_STRATEGY.md) guide.
+
 ## FAQ
 
 ### I Have Issues with Building the Project or Starting the Server
