Background and Motivation

As Django CMS continues to grow in complexity and adoption, ensuring code quality, maintainability, and developer experience is crucial. Typing in Python has proven to be an invaluable tool for achieving these goals, as it:

1. Improves code reliability by catching type-related errors at compile-time.
2. Enhances developer productivity by enabling better editor autocompletion and static analysis tools.
3. Facilitates onboarding by making code more self-documenting.

The Django ecosystem has benefited greatly from django-stubs, an external typing package that enriches Django projects without intrusive modifications to the core. This proposal suggests adopting a similar strategy for Django CMS to increase type coverage and improve code quality.

Objectives

1. Develop an external django-cms-stubs package: Provide type annotations for Django CMS without modifying the core codebase, following the example of django-stubs.
2. Incrementally type-check the core: Ensure all new code contributions include type annotations and encourage contributors to adopt typing in existing code.
3. Integrate static type checking into CI pipelines: Leverage tools like mypy to enforce type correctness in the project.

Proposal Details

1. Creating django-cms-stubs

• Develop a standalone package that provides type stubs for Django CMS.
• Collaborate with the Django CMS community to identify critical modules and interfaces to prioritize for typing.
• Maintain the stubs package in a separate repository under the Django CMS organization for better versioning and community contributions.

Key Deliverables:

• A functional django-cms-stubs package with coverage for core modules such as CMS pages, plugins, templates, and permissions.
• Comprehensive documentation to guide developers on installing and using the stubs.

2. Incremental Typing in Core Code

• Mandate type annotations for all new code contributions to the Django CMS core.
• Identify high-traffic or high-risk areas of the codebase and prioritize them for type coverage.
• Provide a detailed guide on how to add type annotations to existing code.

Key Deliverables:

• A gradual increase in type coverage for the Django CMS core.
• Developer-friendly guidelines for writing and reviewing typed code.

3. CI Integration for Static Type Checking

• Add mypy as a mandatory step in the CI pipeline to ensure type correctness.
• Configure mypy to work seamlessly with the django-cms-stubs package and the Django CMS core.
• Set achievable thresholds for type coverage initially and gradually increase them as the project matures.

Key Deliverables:

• A robust CI pipeline that enforces type checking.
• Regular reports on type coverage to track progress.

Implementation Plan

Phase 1: Research and Planning (TBD)

• Review the existing Django CMS codebase and identify areas suitable for typing.
• Analyze django-stubs to understand its structure and implementation.
• Draft a roadmap for creating django-cms-stubs and incrementally typing the core.

Phase 2: Initial Development (TBD)

• Develop a prototype of the django-cms-stubs package with type annotations for key modules.
• Update the core codebase to enforce type annotations for new contributions.
• Set up mypy in the CI pipeline with initial configuration.

Phase 3: Community Engagement and Rollout (TBD)

• Publish and promote the django-cms-stubs package to the Django CMS community.
• Organize workshops or documentation sprints to help contributors adopt typing.
• Monitor feedback and iterate on the stubs package and CI pipeline.

Phase 4: Scaling and Maintenance (TBD)

• Continuously expand type coverage in the stubs package and core code.
• Adjust CI thresholds to progressively enforce stricter type coverage.
• Encourage community contributions to maintain and improve the typing system.

Benefits to Django CMS

1. Improved code quality: Typing reduces runtime errors and provides clearer documentation.
2. Better developer experience: Enhanced autocompletion and linting improve productivity.
3. Stronger community engagement: A typed codebase attracts more contributors, especially those accustomed to modern Python practices.

Conclusion

Adopting a typing strategy for Django CMS is a forward-thinking step that aligns with industry best practices. By creating an external django-cms-stubs package, mandating type annotations for new code, and integrating static type checking into CI, we can enhance the quality and maintainability of the project without disrupting existing workflows. This approach ensures a smooth transition while maximizing the benefits of typing.