Version 0.3.1 update

.github/report_nightly_build_failure.py

@@ -0,0 +1,28 @@
+
+"""
+Called by GitHub Action when the nightly build fails.
+This reports an error to the #nightly-build-failures Slack channel.
+"""
+import os
+import requests
+
+if "SLACK_WEBHOOK_URL" in os.environ:
+    # https://docs.github.com/en/free-pro-team@latest/actions/reference/environment-variables#default-environment-variables
+    repository = os.environ["GITHUB_REPOSITORY"]
+    run_id = os.environ["GITHUB_RUN_ID"]
+    url = f"https://github.com/{repository}/actions/runs/{run_id}"
+
+    print("Reporting to #nightly-build-failures slack channel")
+    response = requests.post(
+        os.environ["SLACK_WEBHOOK_URL"],
+        json={
+            "text": f"A Nightly build failed. See {url}",
+        },
+    )
+
+    print(f"Slack responded with: {response}")
+
+else:
+    print(
+        "Unable to report to #nightly-build-failures slack channel because SLACK_WEBHOOK_URL is not set"
+    )

.github/workflows/nightly-tests.yml

@@ -0,0 +1,35 @@
+name: Nightly Wagtail test
+
+on:
+  schedule:
+    - cron: "20 1 * * *"
+
+  workflow_dispatch:
+
+jobs:
+  nightly-test:
+    # Cannot check the existence of secrets, so limiting to repository name to prevent all forks to run nightly.
+    # See: https://github.com/actions/runner/issues/520
+    if: ${{ github.repository == 'torchbox/wagtail-experiments' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "git+https://github.com/wagtail/wagtail.git@main#egg=wagtail"
+          pip install -e .[testing]
+      - name: Test
+        id: test
+        continue-on-error: true
+        run: ./runtests.py
+      - name: Send Slack notification on failure
+        if: steps.test.outcome == 'failure'
+        run: |
+          python .github/report_nightly_build_failure.py
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

.github/workflows/test.yml

@@ -0,0 +1,85 @@
+
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+# Current configuration:
+# - django 3.2, python 3.8, wagtail 4.1, postgres
+# - django 4.0, python 3.9, wagtail 5.0, sqlite
+# - django 4.1, python 3.10, wagtail 5.1, postgres
+# - django 4.2, python 3.11, wagtail 5.2, sqlite
+# - django 4.2, python 3.12, wagtail main, sqlite (allow failures)
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ matrix.experimental }}
+    strategy:
+      matrix:
+        include:
+          - python: "3.8"
+            django: "Django>=3.2,<4.0"
+            wagtail: "wagtail>=4.1,<4.2"
+            database: "postgresql"
+            modeladmin: false
+            experimental: false
+          - python: "3.9"
+            django: "Django>=4.0,<4.1"
+            wagtail: "wagtail>=5.0,<5.1"
+            database: "sqlite3"
+            modeladmin: false
+            experimental: false
+          - python: "3.10"
+            django: "Django>=4.1,<4.2"
+            wagtail: "wagtail>=5.1,<5.2"
+            database: "postgresql"
+            modeladmin: true
+            experimental: false
+          - python: "3.11"
+            django: "Django>=4.2,<4.3"
+            wagtail: "wagtail>=5.2,<5.3"
+            database: "sqlite3"
+            modeladmin: true
+            experimental: false
+
+          - python: "3.12"
+            django: "Django>=4.2,<4.3"
+            wagtail: "git+https://github.com/wagtail/wagtail.git@main#egg=wagtail"
+            database: "sqlite3"
+            modeladmin: true
+            experimental: true
+
+    services:
+      postgres:
+        image: postgres:14
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "psycopg2>=2.9.3"
+          pip install "${{ matrix.django }}"
+          pip install "${{ matrix.wagtail }}"
+          pip install -e .[testing]
+      - name: Install wagtail-modeladmin
+        if: ${{ matrix.modeladmin }}
+        run: pip install wagtail-modeladmin
+      - name: Test
+        run: ./runtests.py
+        env:
+          DATABASE_ENGINE: django.db.backends.${{ matrix.database }}
+          DATABASE_HOST: localhost
+          DATABASE_USER: postgres
+          DATABASE_PASS: postgres

.gitignore

@@ -1,4 +1,5 @@
 *.pyc
 /.tox/
 /dist/
+/build/
 /wagtail_experiments.egg-info/

CHANGELOG.txt

@@ -1,6 +1,21 @@
 Changelog
 =========
 
+0.3.1 (2023-11-06)
+~~~~~~~~~~~~~~~~~~
+
+ * Use external wagtail-modeladmin package where available
+ * Added support for Wagtail 5.1 - 5.2 and provisional support for Wagtail 6.0
+
+
+0.3 (2023-08-10)
+~~~~~~~~~~~~~~~~
+
+ * Added support for Wagtail 4.1 thru 5.0
+ * Added support for Django 3.2 thru 4.2
+ * Added docstrings to all 'experiment' functions and classes.
+ * Support internationalization for models
+
 0.2 (28.11.2018)
 ~~~~~~~~~~~~~~~~
 

README.rst

@@ -3,9 +3,6 @@
 Wagtail Experiments
 ===================
 
-.. image:: https://api.travis-ci.org/torchbox/wagtail-experiments.svg?branch=master
-    :target: https://travis-ci.org/torchbox/wagtail-experiments
-
 **A/B testing for Wagtail**
 
 This module supports the creation of A/B testing experiments within a Wagtail site. Several alternative versions of a page are set up, and on visiting a designated control page, a user is presented with one of those variations, selected at random (using a simplified version of the `PlanOut algorithm <https://facebook.github.io/planout/>`_). The number of visitors receiving each variation is logged, along with the number that subsequently go on to complete the experiment by visiting a designated goal page.
@@ -14,7 +11,32 @@ This module supports the creation of A/B testing experiments within a Wagtail si
 Installation
 ------------
 
-wagtail-experiments is compatible with Wagtail 1.7 to 2.3, and Django 1.8 to 2.1. To install::
+wagtail-experiments is compatible with Wagtail 4.1 to 5.2, and Django 3.2 to 4.2. It depends on the Wagtail ModelAdmin module, which is available as an external package as of Wagtail 5.0; we recommend using this rather than the bundled `wagtail.contrib.modeladmin` module to avoid deprecation warnings. The external package will be required as of Wagtail 6.0.
+
+### On Wagtail 5.0 and above
+
+To install::
+
+    pip install wagtail-experiments wagtail-modeladmin
+
+and ensure that the apps ``wagtail_modeladmin`` and ``experiments`` are included in your project's ``INSTALLED_APPS``:
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        # ...
+        'wagtail_modeladmin',
+        'experiments',
+        # ...
+    ]
+
+Then migrate::
+
+    ./manage.py migrate
+
+### On Wagtail 4.x
+
+To install::
 
     pip install wagtail-experiments
 
@@ -29,7 +51,7 @@ and ensure that the apps ``wagtail.contrib.modeladmin`` and ``experiments`` are
         # ...
     ]
 
-Then migrate:: 
+Then migrate::
 
     ./manage.py migrate
 

experiments/admin_urls.py

@@ -1,12 +1,10 @@
-from __future__ import absolute_import, unicode_literals
-
-from django.urls import path
+from django.urls import re_path
 from experiments import views
 
 app_name = 'experiments'
 
 urlpatterns = [
-    path('experiment/report/<int:experiment_id>/', views.experiment_report, name='report'),
-    path('experiment/select_winner/<int:experiment_id>/<int:variation_id>/', views.select_winner, name='select_winner'),
-    path('experiment/report/preview/<int:experiment_id>/<int:page_id>/', views.preview_for_report, name='preview_for_report'),
+    re_path(r'^experiment/report/(\d+)/$', views.experiment_report, name='report'),
+    re_path(r'^experiment/select_winner/(\d+)/(\d+)/$', views.select_winner, name='select_winner'),
+    re_path(r'^experiment/report/preview/(\d+)/(\d+)/$', views.preview_for_report, name='preview_for_report'),
 ]

experiments/backends/db.py

@@ -1,13 +1,24 @@
-from __future__ import absolute_import, unicode_literals
-
 import datetime
-
 from django.db.models import F, Sum
 
 from experiments.models import ExperimentHistory
 
 #TODO: potentially the same session? clearing cookies
 def record_participant(experiment, user_id, variation, request):
+    '''
+        If the user hasn't already participated in this experiment,
+        then save the variation the user viewed.
+
+        Args:
+            experiment: instance of experiments.models.Experiment
+            user_id:    the id for this user.
+            variation:  variation user viewed.
+            request:    django HttpRequest.
+
+        Return:
+            Nothing
+    '''
+
     # abort if this user has participated already
     experiments_started = request.session.get('experiments_started', [])
     if experiment.id in experiments_started:
@@ -23,8 +34,21 @@ def record_participant(experiment, user_id, variation, request):
     # increment the participant_count
     ExperimentHistory.objects.filter(pk=history.pk).update(participant_count=F('participant_count') + 1)
 
-
 def record_completion(experiment, user_id, variation, request):
+    '''
+        If the user has started this experiment, but not completed it yet,
+        then mark the user's participation as completed.
+
+        Args:
+            experiment: instance of experiments.models.Experiment
+            user_id:   the id for this user.
+            variation: variation user viewed.
+            request:   django HttpRequest.
+
+        Return:
+            Nothing
+    '''
+
     # abort if this user never started the experiment
     if experiment.id not in request.session.get('experiments_started', []):
         return
@@ -46,6 +70,16 @@ def record_completion(experiment, user_id, variation, request):
 
 
 def get_report(experiment):
+    '''
+        Generate a report about the experiment's results.
+
+        Args:
+            experiment: instance of experiments.models.Experiment
+
+        Return:
+            A report of experiment results as a dictionary.
+    '''
+
     result = {}
     result.setdefault('variations', [])