added new upgrade guide

NEW_UPGRADE_GUIDE.md

@@ -0,0 +1,168 @@
+**Python 3 and Plone 5 Compatibility**
+
+SENAITE is a complex Laboratory Information Management System (LIMS). Modernizing the project to support Python 3 and Plone 5 requires a phased approach to ensure stability and maintainability. This guide outlines a structured plan for the upgrade.
+
+1. **Assessment and Planning**
+
+    **1.1. Code Audit**
+
+    - Conduct a comprehensive audit of the codebase to identify:
+        - Python 2-specific constructs (e.g., print statements, unicode handling, old-style classes).
+        - Dependencies specific to Plone 4 and Archetypes.
+        - Areas of tight coupling between the codebase and deprecated features of Python 2 or Plone 4.
+
+    **Tools to Use:**
+
+    - [pylint](https://pylint.pycqa.org/) with Python 3 plugins for compatibility checks.
+    - [caniusepython3](https://pypi.org/project/caniusepython3/) to identify dependencies blocking Python 3 support.
+    - Custom scripts to scan for Archetypes usage and old API patterns.
+
+    **1.2. Dependency Review**
+
+    - Create a dependency list and document the compatibility status for each library.
+    - Check if older libraries (e.g., Plone add-ons) have updated versions or alternatives.
+
+**Steps:**
+
+1. Audit dependencies using pip list and dependency tools.
+2. For unmaintained libraries, assess replacement options or plan to fork and modernize them.
+3. Document compatibility for:
+    - Plone 5 ecosystem libraries.
+    - Python 3-compatible versions of Plone add-ons and utilities.
+1. **Preparation**
+
+    **2.1. Freeze the Existing Codebase**
+
+    - Create a maintenance branch for ongoing bug fixes and support in the legacy Python 2/Plone 4 environment.
+
+    **2.2. Set Up Development Environments**
+
+    - Establish separate environments for Python 3/Plone 5 migration:
+    - Use venv or tools like Docker to isolate the development environment.
+    - Install Plone 5 in a clean environment for testing.
+
+    **2.3. Continuous Integration (CI) Setup**
+
+    - Configure CI pipelines to test the codebase in both environments:
+        - Python 2.7 and Plone 4.
+        - Python 3.9+ and Plone 5.
+    - Recommended tools: **GitHub Actions**, **GitLab CI/CD**, or **Jenkins**.
+2. **Python 2 to Python 3 Migration**
+
+    **3.1. Recommended Approach**
+
+    - Avoid heavy reliance on six for long-term maintainability. Instead:
+        - Use **modernization-first** tools like 2to3 to perform initial changes.
+        - Gradually refactor Python 2-specific constructs into Python 3.
+
+    **Steps:**
+
+    1. Add __future__ imports to ease transitions:
+
+```python
+	from __future__ import print_function, division, unicode_literals 
+```
+
+1. Replace Python 2 idioms with Python 3 equivalents:
+    - Replace xrange with range.
+    - Use list(dict.keys()) instead of dict.keys().
+    - Handle string and byte conversions explicitly using str and bytes.
+    - Use f-strings for improved readability (Python 3.6+).
+    - Remove obsolete Python 2 imports like StringIO.
+
+    **Testing:**
+
+    - Test with tools like tox to verify compatibility across Python versions.
+    - Use pytest and ensure existing test cases pass under Python 3.
+
+**3.2. Handling Legacy Constructs**
+
+- Replace __metaclass__ with Python 3 class-based syntax.
+- Refactor deprecated exception handling (e.g., except Exception, e to except Exception as e).
+- Update file handling to use the with open(...) syntax.
+
+**3.3. Library Updates**
+
+- Upgrade libraries to Python 3-compatible versions or find alternatives.
+- Replace deprecated libraries (e.g., urllib2 with urllib.request).
+1. **Plone 4 to Plone 5 Migration**
+
+    **4.1. Content Type Migration: Dexterity vs Archetypes**
+
+    **Recommendation**: Transition to **Dexterity** content types for the following reasons:
+
+    - Dexterity is the default in Plone 5 and beyond.
+    - It provides better customization and extensibility.
+    - Migration tools like [collective.transmogrifier](https://github.com/collective/collective.transmogrifier) can assist in converting content from Archetypes.
+
+    **Migration Process:**
+
+    1.  Audit current Archetypes content types.
+    2. Use collective.transmogrifier to map and migrate data.
+    3. Refactor custom logic to align with Dexterity schema and views.
+
+    **4.2. UI and Template Updates**
+
+    - Update templates to use Plone 5’s barceloneta theme.
+    - Refactor views to leverage Plone 5’s modernized UI components.
+    - Replace deprecated Plone 4 patterns with Plone 5 standards.
+
+    **4.3. Workflow and Permissions**
+
+    - Review existing workflows and update them to align with Plone 5’s enhanced workflow engine.
+
+**4.4. Registry and Configuration Updates**
+
+- Replace XML configurations with Plone 5’s registry-based system.
+- Use Plone’s plone.registry to manage configuration changes.
+1. **Phased Rollout**
+
+    **5.1. Phase 1: Python 3 Compatibility**
+
+    - Focus first on achieving Python 3 compatibility while maintaining Plone 4 support.
+    - Test exhaustively with dual-environment CI pipelines.
+    - Once stable, drop Python 2 support and remove compatibility workarounds.
+
+    **5.2. Phase 2: Full Plone 5 Migration**
+
+    - Transition the main branch to Plone 5 and drop Plone 4 support.
+    - Migrate all content types to Dexterity.
+2. **Testing and Validation**
+
+    **6.1. Unit Tests**
+
+    - Extend unit test coverage to include all critical functionality.
+    - Use pytest-cov to measure test coverage and identify gaps.
+
+    **6.2. Functional and Integration Tests**
+
+    - Automate end-to-end testing with tools like **Selenium** or **Robot Framework**.
+    - Validate UI workflows and backend integrations.
+
+    **6.3. Performance Testing**
+
+    - Benchmark key operations to compare performance under Python 2/Plone 4 and Python 3/Plone 5.
+3. **Documentation and Training**
+
+    **7.1. Update Documentation**
+
+    - Update developer documentation to reflect Python 3 and Plone 5 changes.
+    - Revise user guides to accommodate Dexterity content types and new UI workflows.
+
+    **7.2. Provide Training**
+
+    - Train developers on Python 3 best practices and Plone 5 features.
+    - Create video tutorials or webinars for end users.
+4. **Release Strategy**
+
+    **8.1. Beta Release**
+
+    - Release beta versions for community feedback.
+    - Address bugs and issues reported by users.
+
+    **8.2. Stable Release**
+
+    - After thorough testing, release a stable version and document the upgrade process for users.
+5. **Long-Term Maintenance**
+- Establish processes for regular updates to keep pace with Python and Plone improvements.
+- Prioritize modular, maintainable code to simplify future upgrades.