Version 3.11.0 (upcoming)

Migration Guide for Version 3.11.0 🚀

Version 3.11.0 adds one new model, Unavailability, so this upgrade does require a migration. No existing field changes meaning, nothing is renamed, and no data is rewritten — the migration only creates the new table.

It also raises the minimum Python version. Check that first.

Before you start: supported versions

Declared in setup.cfg	3.10.1	3.11.0
python_requires	>=3.8	>=3.10
Django	>=4.2,<6.0	>=4.2,<7.0
Tested combinations	Python 3.10 – 3.11	Python 3.10 – 3.14, Django 4.2 – 6.1

Python 3.8 and 3.9 are no longer accepted. pip will refuse to install 3.11.0 on them rather than installing something broken, so if you are still on either, stay on 3.10.1 until you can upgrade the interpreter.

The compatibility matrix has the full grid of tested Python and Django combinations.

Steps for Upgrading to Version 3.11.0:

1. Backup Your Database:

   • As a best practice, always back up your current database before performing an upgrade. This precaution ensures you can restore your application to its previous state if needed.

2. Update Package:

   • Upgrade to the latest version by running:

     pip install --upgrade django-appointment
     

3. Run Migrations:

   • This package intentionally does not ship migration files, so generate them against your own project first:

     python manage.py makemigrations appointment
     python manage.py migrate
     

   • What the migration creates:

   Model	Change
   Unavailability	New table: staff_member, date, start_time, end_time, description, plus a check constraint enforcing start_time < end_time

   • Nothing else in the schema changes. If makemigrations proposes anything beyond creating that table, stop and compare it against your previous migrations before applying it.

4. Check your StaffMember rows:

   • From this release, creating a StaffMember grants that user Django's is_staff flag. Existing rows are not backfilled. If you have staff members created outside the "create new staff member" flow — through the Django admin, a fixture, or a data migration — they may still be missing the flag and therefore be unable to reach the administration pages. To grant it to everyone who has a StaffMember record:

     from django.contrib.auth import get_user_model
     from appointment.models import StaffMember
     
     get_user_model().objects.filter(
         pk__in=StaffMember.objects.values('user_id'), is_staff=False, is_superuser=False
     ).update(is_staff=True)
     

   • Conversely, if you deliberately keep staff members out of Django's staff group, review that decision: the administration views have always gated on is_staff, so those users were not reaching the pages anyway.

5. Review your deprecation warnings:

   • convert_12_hour_time_to_24_hour_time() and convert_24_hour_time_to_12_hour_time() now emit a DeprecationWarning and will be removed in 4.0.0. They are no longer used internally. If your own code calls them, move to django.utils.formats.time_format() or the time template filter.
   • exclude_booked_slots() also emits a DeprecationWarning. It still works, but it cannot exclude unavailabilities or apply the newer slot rules — switch to exclude_unavailable_slots(), noting the argument order changed: exclude_unavailable_slots(slots, appointments=..., slot_duration=...).
   • Run your test suite with -W error::DeprecationWarning to find the call sites.

6. Review and Test:

   • After upgrading, thoroughly test your application to ensure all functionalities are working as expected with the new version.
   • Pay particular attention to any page that displays a date or a time. This release moved the remaining hardcoded formats onto Django's localization, so dates, time slots and the down payment now follow the active locale. If you had worked around the previous US-formatted output, that workaround is likely to be wrong now.
   • If you override the administration templates, check the date and time pickers specifically: they are configured from localized_formats in the generic context. See Custom templates.

Optional follow-ups

• Unavailabilities: nothing to do unless you want them. They are opt-in per staff member, and a staff member with no unavailability behaves exactly as before. See the model reference for how they interact with slot availability.
• Django 6: the package now supports it, but upgrading Django is a separate exercise. Do one at a time.

Troubleshooting:

• makemigrations wants to alter constraints it should not:
  • CheckConstraint's check argument was renamed to condition in Django 5.1. The package handles both through appointment/compat.py, but a project holding migrations generated under an older Django may see a no-op constraint change proposed on first run. It is harmless to apply.
• Issues Post Migration:
  • If you encounter issues after migration, consult the release notes for the specific updates that might affect your setup.
  • Check the Django logs for any error messages that can provide insights into issues.

Important Notes 📝:

• As with any upgrade, testing in a development or staging environment before applying changes to your production environment is highly recommended.
• Upgrading from the 3.10 series? Read the 3.10 migration guide first if you skipped it — that release added four model fields.
• Upgrading from a version before 2.0.0? Read the 2.1.0 migration guide first — that release did change the schema significantly.