build: Restructure repo & rename to xblocks-core

Part of: #237
Part of: #149

Author: kdmccormick

.coveragerc

@@ -1,5 +1,4 @@
 [run]
 branch = True
 source =
-    xblocks_contrib
-    xblock_pdf
+    src

.gitignore

@@ -81,8 +81,7 @@ output/*/index.html
 # Sphinx
 docs/_build/
 docs/modules.rst
-docs/xblocks_contrib.rst
-docs/xblocks_contrib.*.rst
+docs/xblock_*.rst
 
 # Private requirements
 requirements/private.in

CHANGELOG.rst

@@ -2,7 +2,7 @@ Change Log
 ##########
 
 ..
-   All enhancements and patches to xblocks-contrib will be documented
+   All enhancements and patches to xblocks-core will be documented
    in this file.  It adheres to the structure of https://keepachangelog.com/ ,
    but in reStructuredText instead of Markdown (for ease of incorporation into
    Sphinx documentation and the PyPI description).
@@ -14,6 +14,15 @@ Change Log
 Unreleased
 **********
 
+* Renamed pypi package and repo from ``xblocks-contrib`` to ``xblocks-core``.
+* Restructured Python source into ``src/xblock_<name>/`` packages (one per XBlock); the shared
+  XML helpers moved to ``src/xblocks_core.legacy_utils/``.
+* Renamed Django app entry points ``xblocks_contrib_problem_capa`` → ``xblock_problem_capa`` and
+  ``xblocks_contrib_discussion`` → ``xblock_discussion`` (consumers in edx-platform must update
+  ``INSTALLED_APPS`` and any direct imports).
+* Renamed Transifex resource slugs ``xblocks-contrib-<name>`` → ``xblocks-core-<name>``; the
+  combined source ``django.po`` now lives at ``src/xblocks_core_locale/conf/locale/en/LC_MESSAGES/``.
+
 0.16.0 - 2026-04-21
 **********************************************
 

MANIFEST.in

@@ -4,30 +4,29 @@ include requirements/base.in
 include requirements/constraints.txt
 
 # --- PACKAGE DATA ---
-recursive-include xblocks_contrib *.html *.js *.css *.jar *.png *.gif *.jpg *.jpeg *.svg *.yaml *.underscore
-recursive-include xblock_pdf *.html *.js *.css
+recursive-include src *.html *.js *.css *.jar *.png *.gif *.jpg *.jpeg *.svg *.yaml *.underscore
 
 # --- EXCLUSIONS ---
 # Prevent raw frontend source files and node_modules from bloating the Python wheel.
-prune xblocks_contrib/*/assets
-prune xblocks_contrib/*/node_modules
+prune src/*/assets
+prune src/*/node_modules
 global-exclude webpack*.config.js karma*.js package*.json package-lock.json .gitignore
 
 # Exclude top-level tests and JS specs by default to keep the distribution size small.
-# NOTE: The `*` here only looks one directory deep (e.g., `foo/tests`). 
-prune */tests
-prune */spec
+# NOTE: The `*` here only looks one directory deep (e.g., `foo/tests`).
+prune src/*/tests
+prune src/*/spec
 
 # Because MANIFEST.in does not support `**` (globstar) for infinite folder depth,
 # generic wildcards cannot reach deeply nested folders. We must explicitly prune
 # these deep directories to prevent them from being swept up by `recursive-include`.
-prune xblocks_contrib/problem/capa/static/js/capa/spec
-prune xblocks_contrib/problem/capa/static/js/capa/fixtures
-prune xblocks_contrib/problem/capa/tests/test_files
+prune src/xblock_problem/capa/static/js/capa/spec
+prune src/xblock_problem/capa/static/js/capa/fixtures
+prune src/xblock_problem/capa/tests/test_files
 
 # --- TEST UTILITY INCLUSIONS ---
 # Re-include specific test files that are excluded above.
 # We do this because openedx-platform imports these specific test helpers.
-include xblocks_contrib/problem/capa/tests/test_util.py
-include xblocks_contrib/problem/capa/tests/helpers.py
-include xblocks_contrib/problem/capa/tests/response_xml_factory.py
+include src/xblock_problem/capa/tests/test_util.py
+include src/xblock_problem/capa/tests/helpers.py
+include src/xblock_problem/capa/tests/response_xml_factory.py

Makefile

@@ -5,10 +5,12 @@
 .PHONY: detect_changed_source_translations dummy_translations build_dummy_translations
 .PHONY: validate_translations pull_translations push_translations install_transifex_clients
 
-PACKAGE_NAME := xblocks_contrib
+SRC_DIR := src
 EXTRACT_DIR := conf/locale/en/LC_MESSAGES
-COMBINED_LOCALE_DIR := $(PACKAGE_NAME)/conf/locale/en/LC_MESSAGES
-JS_TARGET := $(PACKAGE_NAME)/public/js/translations
+# Combined-locale output for the openedx-translations pipeline (OEP-58),
+# which expects a single `django.po` source file per repository.
+COMBINED_LOCALE_DIR := $(SRC_DIR)/xblocks_core_locale/conf/locale/en/LC_MESSAGES
+JS_TARGET := $(SRC_DIR)/xblocks_core_locale/public/js/translations
 
 help:
 	@perl -nle'print $& if m{^[\.a-zA-Z_-]+:.*?## .*$$}' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m  %-25s\033[0m %s\n", $$1, $$2}'
@@ -37,8 +39,8 @@ piptools: ## install pinned version of pip-compile and pip-sync
 requirements: piptools ## install development environment requirements
 	pip-sync -q requirements/dev.txt requirements/private.*
 
-# XBlock directories
-XBLOCKS=$(shell find $(shell pwd)/$(PACKAGE_NAME) -mindepth 2 -maxdepth 2 -type d -name 'conf' -exec dirname {} \;)
+# XBlock directories: each src/xblock_<name>/ that has its own conf/ subdir
+XBLOCKS=$(shell find $(shell pwd)/$(SRC_DIR) -mindepth 2 -maxdepth 2 -type d -name 'conf' -exec dirname {} \;)
 
 ## Localization targets
 

README.rst

@@ -1,6 +1,6 @@
-===============
-xblocks-contrib
-===============
+============
+xblocks-core
+============
 
 This repository is the new home for XBlocks which are part of the base openedx-platform
 installation.
@@ -71,8 +71,8 @@ For information on how to enable translations, visit the `Open edX XBlock tutori
 
 The included Makefile contains targets for extracting, compiling and validating translatable strings.
 Each XBlock in this repository has its own translation configuration under
-``xblocks_contrib/<xblock>/conf/locale/`` and its own Transifex resource mapping under
-``xblocks_contrib/<xblock>/.tx/config``. All Make targets iterate over every XBlock automatically.
+``src/xblock_<name>/conf/locale/`` and its own Transifex resource mapping under
+``src/xblock_<name>/.tx/config``. All Make targets iterate over every XBlock automatically.
 
 The general steps to provide multilingual messages for a Python program (or an XBlock) are:
 
@@ -132,11 +132,11 @@ This iterates over every XBlock and:
 
 The output for each XBlock is a single file at::
 
-    xblocks_contrib/<xblock>/conf/locale/en/LC_MESSAGES/text.po
+    src/xblock_<name>/conf/locale/en/LC_MESSAGES/text.po
 
 Additionally, all per-xblock ``text.po`` files are merged into a single combined file at::
 
-    xblocks_contrib/conf/locale/en/LC_MESSAGES/django.po
+    src/xblocks_core_locale/conf/locale/en/LC_MESSAGES/django.po
 
 This combined file is used by the
 `openedx-translations <https://github.com/openedx/openedx-translations>`_ pipeline (OEP-58)

catalog-info.yaml

@@ -7,7 +7,7 @@
 apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:
-  name: xblocks-contrib
+  name: xblocks-core
   annotations:
     openedx.org/component-type: "XBlock"
     openedx.org/arch-interest-groups: "feanil"

docs/Makefile

@@ -96,9 +96,9 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/xblocks-contrib.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/xblocks-core.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/xblocks-contrib.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/xblocks-core.qhc"
 
 .PHONY: applehelp
 applehelp:
@@ -115,8 +115,8 @@ devhelp:
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/xblocks-contrib"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/xblocks-contrib"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/xblocks-core"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/xblocks-core"
 	@echo "# devhelp"
 
 .PHONY: epub

docs/conf.py

@@ -1,6 +1,6 @@
 # pylint: disable=invalid-name
 """
-xblocks-contrib documentation build configuration file.
+xblocks-core documentation build configuration file.
 
 This file is execfile()d with the current directory set to its
 containing dir.
@@ -54,7 +54,7 @@ def get_version(*file_paths):
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 sys.path.append(REPO_ROOT)
 
-VERSION = get_version("../xblocks_contrib", "__init__.py")
+VERSION = get_version("../src/xblocks_core", "__init__.py")
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -103,17 +103,17 @@ def get_version(*file_paths):
 top_level_doc = "index"
 
 # General information about the project.
-project = "xblocks-contrib"
+project = "xblocks-core"
 copyright = f"{datetime.now().year}, Axim Collaborative, Inc."  # pylint: disable=redefined-builtin
 author = "Axim Collaborative, Inc."
-project_title = "xblocks-contrib"
+project_title = "xblocks-core"
 documentation_title = f"{project_title}"
 
 # Set display_github to False if you don't want "edit on Github" button
 html_context = {
     "display_github": True,  # Integrate GitHub
     "github_user": "edx",  # Username
-    "github_repo": "xblocks-contrib",  # Repo name
+    "github_repo": "xblocks-core",  # Repo name
     "github_version": "main",  # Version
     "conf_py_path": "/docs/",  # Path in the checkout to the docs root
 }
@@ -198,7 +198,7 @@ def get_version(*file_paths):
 # documentation.
 #
 html_theme_options = {
-    "repository_url": "https://github.com/openedx/xblocks-contrib",
+    "repository_url": "https://github.com/openedx/xblocks-core",
     "repository_branch": "main",
     "path_to_docs": "docs/",
     "home_page_in_toc": True,
@@ -235,7 +235,7 @@ def get_version(*file_paths):
 # The name for this set of Sphinx documents.
 # "<project> v<release> documentation" by default.
 #
-# html_title = 'xblocks-contrib v0.1.0'
+# html_title = 'xblocks-core v0.1.0'
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #
@@ -551,8 +551,7 @@ def on_init(app):  # pylint: disable=unused-argument
             apidoc_path,
             "-o",
             docs_path,
-            os.path.join(root_path, "xblocks_contrib"),
-            os.path.join(root_path, "xblocks_contrib/migrations"),
+            os.path.join(root_path, "src"),
         ]
     )
 

docs/decisions/0002-pointer-tags-handling.rst

@@ -54,7 +54,7 @@ Both formats are supported by edx-platform's `XmlMixin`, which handles:
 - **Parsing:** detecting pointer tags and loading their definitions from the pointed-to file.
 - **Exporting:** serializing blocks in pointer format.
 
-However, this was disrupted when **built-in XBlocks** (such as `WordCloud`, `Annotatable`, `LTI`, `HTML`, `Poll`, `Video`, `Problem`) were **extracted from edx-platform** into a new repository: **xblocks-contrib**.
+However, this was disrupted when **built-in XBlocks** (such as `WordCloud`, `Annotatable`, `LTI`, `HTML`, `Poll`, `Video`, `Problem`) were **extracted from edx-platform** into a new repository: **xblocks-core**.
 
 The key architectural change was that **extracted XBlocks no longer depend on `XmlMixin`** and instead inherit directly from the base `XBlock` class — following the *pure XBlock* pattern.
 This transition removed pointer-tag handling functionality for those blocks.
@@ -115,4 +115,4 @@ References
 
 - `openedx/XBlock#830` - Initial attempt to add pointer-tag parsing to XBlock core
 - `openedx/edx-platform#37133` - Runtime-based pointer resolution PR
-- `xblocks_contrib` - Repository containing extracted XBlocks and new `PointerTagMixin`
+- `xblocks-core` - Repository containing extracted XBlocks and new `PointerTagMixin`