diff --git a/README.md b/README.md index cc24be68a..fff393ea0 100644 --- 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 new file mode 100644 index 000000000..eb02ae565 --- /dev/null +++ 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 new file mode 100644 index 000000000..eb02ae565 --- /dev/null +++ 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 index d121dc353..153005b05 100644 --- 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