Sumac Release Notes

[feoh]

Things that can be done before the release is cut

• find the date for the previous release (for Redwood, this was June 19, 2024)
• find the date for the next release (for Teak, this will be June 09, 2025)
• Create a wiki page for the next release, on the Open edX Release Planning wiki page (Teak)

Things to do after the release is cut

• add an appropriate TOC to the release notes
• add any items from the Pending Release wiki page
• Review and incorporate any feature posts from edX Partner announcements
• Review and incorporate any feature posts from the open edX blog
• Review commit messages from relevant repos. Dinghy seems like a useful tool for this. I used this config olive-dinghy.yaml
• Review DEPR tickets
• Diff the technical documentation and build a list of links to both new and removed settings.

Meta tasks

• Review and update this checklist

[feoh]

Currently stuck trying to make doc:

~/src/openedx/edx-platform (open-release/sumac.master*) » make docs                                                                                                                          [.venv] feoh@prometheus
DJANGO_SETTINGS_MODULE=docs.docs_settings python manage.py lms generate_swagger --generator-class=edx_api_doc_tools.ApiSchemaGenerator -o docs/lms-openapi.yaml
Traceback (most recent call last):
  File "/home/feoh/src/openedx/edx-platform/manage.py", line 103, in <module>
    startup.run()
  File "/home/feoh/src/openedx/edx-platform/lms/startup.py", line 20, in run
    django.setup()
  File "/home/feoh/src/openedx/edx-platform/.venv/lib/python3.12/site-packages/django/__init__.py", line 24, in setup
    apps.populate(settings.INSTALLED_APPS)
  File "/home/feoh/src/openedx/edx-platform/.venv/lib/python3.12/site-packages/django/apps/registry.py", line 124, in populate
    app_config.ready()
  File "/home/feoh/src/openedx/edx-platform/.venv/lib/python3.12/site-packages/django/contrib/admin/apps.py", line 27, in ready
    self.module.autodiscover()
  File "/home/feoh/src/openedx/edx-platform/.venv/lib/python3.12/site-packages/django/contrib/admin/__init__.py", line 50, in autodiscover
    autodiscover_modules("admin", register_to=site)
  File "/home/feoh/src/openedx/edx-platform/.venv/lib/python3.12/site-packages/django/utils/module_loading.py", line 58, in autodiscover_modules
    import_module("%s.%s" % (app_config.name, module_to_search))
  File "/home/feoh/.pyenv/versions/3.12.4/lib/python3.12/importlib/__init__.py", line 90, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "<frozen importlib._bootstrap>", line 1387, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1360, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1331, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 935, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 995, in exec_module
  File "<frozen importlib._bootstrap>", line 488, in _call_with_frames_removed
  File "/home/feoh/src/openedx/edx-platform/cms/djangoapps/contentstore/admin.py", line 21, in <module>
    from .tasks import update_outline_from_modulestore_task, update_all_outlines_from_modulestore_task
  File "/home/feoh/src/openedx/edx-platform/cms/djangoapps/contentstore/tasks.py", line 43, in <module>
    from cms.djangoapps.contentstore.courseware_index import (
  File "/home/feoh/src/openedx/edx-platform/cms/djangoapps/contentstore/courseware_index.py", line 15, in <module>
    from cms.djangoapps.contentstore.course_group_config import GroupConfiguration
  File "/home/feoh/src/openedx/edx-platform/cms/djangoapps/contentstore/course_group_config.py", line 12, in <module>
    from cms.djangoapps.contentstore.utils import reverse_usage_url
  File "/home/feoh/src/openedx/edx-platform/cms/djangoapps/contentstore/utils.py", line 37, in <module>
    from cms.djangoapps.contentstore.toggles import (
  File "/home/feoh/src/openedx/edx-platform/cms/djangoapps/contentstore/toggles.py", line 5, in <module>
    from openedx.core.djangoapps.content.search import api as search_api
  File "/home/feoh/src/openedx/edx-platform/openedx/core/djangoapps/content/search/api.py", line 27, in <module>
    from openedx.core.djangoapps.content.search.models import get_access_ids_for_request
  File "/home/feoh/src/openedx/edx-platform/openedx/core/djangoapps/content/search/models.py", line 15, in <module>
    class SearchAccess(models.Model):
  File "/home/feoh/src/openedx/edx-platform/.venv/lib/python3.12/site-packages/django/db/models/base.py", line 134, in __new__
    raise RuntimeError(
RuntimeError: Model class openedx.core.djangoapps.content.search.models.SearchAccess doesn't declare an explicit app_label and isn't in an application in INSTALLED_APPS.
make: *** [Makefile:34: swagger] Error 1

[feoh]

Got past that, and successfully build xml for toggle flags in redwood!

however, we are blocked in sumac.master, sphinx hangs forever:

~/src/openedx/edx-platform/docs (open-release/sumac.master*) » make xml                                                                           [.venv] feoh@prometheus
sphinx-build -M xml "." "_build"
Running Sphinx v8.1.3
loading translations [en]... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
loading intersphinx inventory 'django' from https://docs.djangoproject.com/en/1.11/_objects/ ...
building [mo]: targets for 0 po files that are out of date
writing output...
building [xml]: targets for 756 source files that are out of date
updating environment: [new config] 756 added, 0 changed, 0 removed
reading sources... [ 56%] references/docstrings/lms/lms.djangoapps.commerce.api.v1

I'll leave it running overnight.

[feoh]

Well it ran for a few hours and then got tactically nuked by Linux's OOM killer. :(

[pomegranited]

Hmm.. I'm having the same issue. To get around it, I added references/docstrings/lms/lms.djangoapps.commerce.api.v1* to the docs/conf.py's exclude_patterns variable which made Sphinx skip it. After doing that, sphinx caught on another one, and so I added it too, and then another..

--- a/docs/conf.py
+++ b/docs/conf.py
@@ -113,7 +113,11 @@ language = 'en'
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store',
+    'references/docstrings/lms/lms.djangoapps.commerce.api.v1*',
+    'references/docstrings/lms/lms.djangoapps.experiments*',
+    'references/docstrings/lms/lms.djangoapps.mobile_api.users*',
+]

 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None

Didn't finish the exercise, but maybe you could use this method this to identify and skip the problem areas, and build the docs you can?

The docs output is awfully noisy, but for "experiments" one, I did find this error:

WARNING: autodoc: failed to import module 'factories' from module 'lms.djangoapps.experiments'; the following exception was raised:
No module named 'factory' [autodoc.import_object]

Unfortunately adding factory to the autodoc_mock_imports in docs/conf.py still didn't let docs build for lms.djangoapps.experiments, so I don't know if this issue is related to the hanging or not.