This document summarizes Susan's presentation on upgrading Django projects. The presentation covered: - Why upgrades are important for getting new features, fixes and security updates. - The steps involved in upgrading include running tests, fixing broken tests one by one, checking that fewer tests fail with each new version, verifying the UI still works, and editing deployment files. - Challenges include dependencies breaking, release notes documenting changes that require code updates, and the repetitive nature of fixing tests across multiple versions. - The key takeaways are to upgrade one version at a time, run and fix tests with each version, read release notes, break tasks into small steps, and use checklists to track progress

1. How to upgrade to the
newest shiniest Django
version
DjangoCon Europe
Susan tan
Cisco in san francisco, CA
1

2. Hello! I’m Susan
• I’m a software engineer at Cisco in San Francisco,
CA.
• Previously worked at a cloud startup Piston.
• Works with python apis, web development, works
on Cisco’s openstack horizon Django project
• Worked on open source Django project
www.openhatch.org
2

3. Quick Audience Survey
How many people currently work on at least
one project with Django
• below 1.6?
• 1.7?
• 1.8?
• 1.9?
3

4. Why should you do an upgrade?
• get new features, bug fixes,
security fixes
• easier to upgrade to the next
version in future
4

5. A.B.C
backwards-incompatible
new features
backwards compatible
backwards-compatible bug
fixes.
Semantic versioning review
major minor patch
Read http://semver.org/
5

6. Django does NOT follow semantic
versioning FYI
6
• Major release number is an extension of minor
release number.
• From semantic versioning, Django 1.7 should be
2.0, because backwards-incompatible.

7. When is right time to upgrade?
• Your project’s Django version is no longer
supported.
• Do a patch upgrade! Always.
• You have an existing comprehensive test
suite.
• If you don’t have a test suite, then now would be a
good time to start writing unit tests.
7

8. 8
Current Django Versions
Source: https://www.djangoproject.com/download/

9. 9
Future Roadmap
Source: https://www.djangoproject.com/download/
[3] Last version to support Python 2.7.

10. • Hard to know how much time or effort it takes
• Hard to know which tests will break or even run
• Hard to know if UI will continue working
• Confirm functionality at every part of
development
• ie: local host, staging, deployment.
10
Why is upgrading a Django project a
difficult thing to do?

11. What does the end product look
like in code?
11

12. 12
Upgrading OpenHatch

13. Upgrading OpenHatch
13
• OpenHatch vendors all its dependencies.
• Commits that are "Add upgraded version of
library Z” with full library source code.
• ~4 weeks to go from broken Django project to
functional upgraded Django project, including
dependency updates.
• Doing frequent git rebasing & resolving merge
conflicts is terrible.

15. What is step zero?
pip uninstall django
pip install django==<NUMBER>
15

16. What NOT to do
Do not skip over versions. If you do, you
will
• miss deprecation warnings
• supported for 2 versions
• have invalid code
• call APIs or use modules that don’t
exist in newer Django version
16

17. What is step 1?
python manage.py tests
Possible results:
1. Your tests may not even run.
2. Your tests may fail.
3. All your tests pass.
17

18. Option 3: All your tests pass right after
installing new Django

19. Option 2: Your tests fail.
What’s next if tests fail?
Fix tests, one at a time
19

21. At the end, what does “SUCCESS”
look like for a fully upgraded project?
In this order:
1. All tests pass with no errors or deprecation
warnings.
2. UI works locally.
3. Deployment works on staging.
4. UI works on staging.
5. Deployment works on production.
6. UI works on production.
21
Break a big task into smaller tasks.

22. What is this entire process?
Run thru these steps in this order:
1. Run existing unit tests. Fix broken tests.
2. Run same existing unit tests. Confirm that
fewer tests fail.
3. Rinse and repeat steps 1-2 continuously
until all tests pass.
4. Check the UI to see if it all still works.
5. Edit deploy script, requirements.txt,
documentation.
22

23. What are the challenges?
23

24. > ls vendor/packages/
BeautifulSoup django-authopenid docutils odict south
Django django-celery feedparser ordereddict sphinx
Jinja2 django-debug-toolbar gdata python-dateutil sqlparse
PyJWT django-extensions ghettoq python-memcached
staticgenerator
PyYaml django-http-proxy html2text python-mimeparse twill
Pygments django-inplaceedit html5lib python-openid twisted
amqp django-invitation importlib python-otp
typecheck
anyjson django-kombu irc python-patch
unicodecsv
beautifulsoup4 django-model-utils jsmin python-social-auth
unittest-xml-reporting
bleach django-picklefield kombu pytz webob
celery django-registration markupsafe
Lots of dependencies may break
24
Options:
1. Upgrade dependency.
2. Patch it yourself (and upstream it).
3. Use a different similar dependency.

25. LOTS of release notes
• Deprecation warnings or test errors will tell
you which release notes to read.
• Replace syntax with newer syntax.
25

26. Some are simple changes
Upgrade to 1.5: Fix deprecation issue with
AdminMediaHandler

27. Edit manage.py when upgrading to Django 1.5
27
Some are simple changes

28. Replace "direct_to_template()" with generic template
view. This is a deprecation documented in Django 1.5
release notes.

29. LOTS of repetition
29

30. Fix the template quotes syntax issue
This syntax issue is documented in release notes when upgrading to Django 1.5.
In templates, change tags like {% url myview %} to {% url "myview" %}

31. Take aways
31
• Do an upgrade 1 version at a time.
• Run unit tests, see what breaks, then fix tests
1 at a time.
• Read release notes.
• Break every task into small steps.
• A checklist helps.
• So does taking notes.

32. 32
How many people have
been planning to do an
upgrade on their Django
project?

33. Announcing Django Upgrade Open
Space
33
Have you done Django upgrades before or are
looking to do so for your personal project(s)?
WHO: Anyone who wants to upgrade their
projects. Anyone with experience with upgrading
projects.
WHAT: Work on your Django project. Mentor(s)
will be there.
WHEN: this Saturday & Sunday mornings

34. Thanks! Hope this helps.
Thanks Cisco for sponsoring
me to go on this trip.
Susan
Twitter: @ArcTanSusan
34