"It doesn't work" - A Djangonaut's Debugging Toolkit

Welcome to the tutorial! I really appreciate the time you've spent so far and the time you spend in the future on this tutorial.

The purpose of this tutorial is to expose you to some of the tools available to you as a Djangonaut to aid you in your debugging adventures.

If you didn't attend the talk or would like to view the slides, you can find them here.

Preamble to the setup

This tutorial is written to give you the experience of working on a real project. There are tests and adjacent functionality. The tests are written so that they all pass for each lab, which means they confirm the bugs you will be finding.

I suggest reviewing the Project Overview page which has high level information on the models. It should make it easier to understand the project.

Regarding debugging methods, a very useful one is to bisect commits or find the last known good version, then compare what doesn't work. That is very easy to do in this environment, but I strongly suggest that you don't do that unless you're stuck.

How the Labs will work

There are a total of 7 labs, numbered 1.1-1.3, 2.1-2.4 (it made sense at the time). Each is structured with a Report, a set of Facts, an Investigation section, a Conclusion and finally Further Consideration.

I suggest using the Investigation section, but if you'd like to avoid any hints in your debugging effort then stop reading after the Report and Facts sections.

The Conclusion section will have the solution(s) while Further Consideration is reserved for asking you to reflect on your own projects.

Getting Setup

This section will provide you with the minimal setup for this tutorial. If you have a preference on setting up a project differently and know that it works, go for it! Do what you're most comfortable.

1. Have Python 3.8+ installed. My assumption is that you have your own setup decided upon. However, if you're unsure where to go for this, I'd recommend using https://www.python.org/downloads/ for today.
2. From the terminal or command prompt, clone the project.

   git clone git@github.com:tim-schilling/debug-tutorial.git

   If you don't have a SSH key setup, you can use:

   git clone https://github.com/tim-schilling/debug-tutorial.git

   If you don't have git installed, you can download the zip file and unpack it.
3. Change into project directory

   cd debug-tutorial

   If you downloaded the zip file, you'll need to cd to the location where you unpacked the archive.

---

Windows warning

If you are comfortable on Windows with Python and have setup multiple projects, ignore this warning. Do what's comfortable.

If not, I highly recommend using the Windows Subsystem for Linux (docs). If you do, the rest of the instructions will work for you. If you don't have access to that please scroll down to Windows non-WSL Setup.

---

MacOS, Linux, Windows WSL Setup

1. From the terminal, create a virtual environment. (venv docs)

   python -m venv venv

2. Active the virtual environment.

   source venv/bin/activate

3. Install the project dependencies.

   pip install -r requirements.txt

4. Create a new .env file.

   cp .env.dist .env

   If you use this for literally anything but this tutorial, please change the SECRET_KEY value in your .env file.
5. Create the database for the project.

   python manage.py migrate

6. Verify the tests currently pass, if they don't and you're not sure why, please ask.

   python manage.py test

7. Create the fake data. This will take a few minutes.

   python manage.py fake_data

8. Create your own super user account. Follow the prompts.

   python manage.py createsuperuser

9. Run the development web server.

   python manage.py runserver

10. Verify the following pages load:
    • http://127.0.0.1:8000/
    • http://127.0.0.1:8000/p/
    • http://127.0.0.1:8000/p/skill-fight-girl-north-production-thus-a-58113/
11. Log into the admin (link) with your super user.
12. Verify the following pages load:
    • http://127.0.0.1:8000/post/create/
    • http://127.0.0.1:8000/analytics/

BOOM! You're done with the setup. Now that we've accomplished the boring stuff, let's get to the dopamine rushes. I mean the bugs.

Proceed to Lab 1.

Windows non-WSL Setup

1. From the command prompt, create a virtual environment.

   python3 -m venv venv

2. Activate the project

   .\venv\Scripts\activate

3. Install the project dependencies.

   pip install -r requirements.txt

4. Create a new .env file.

   copy .env.dist .env

   If you use this for literally anything but this tutorial, please change the SECRET_KEY value in your .env file.
5. Create the database for the project.

   python -m manage migrate

6. Verify the tests currently pass, if they don't and you're not sure why, please ask.

   python -m manage test

7. Create the fake data. This will take a few minutes.

   python -m manage fake_data

8. Create your own super user account. Follow the prompts.

   python -m manage createsuperuser

9. Run the development web server.

   python -m manage runserver

10. Verify the following pages load:
    • http://127.0.0.1:8000/
    • http://127.0.0.1:8000/p/
    • http://127.0.0.1:8000/p/skill-fight-girl-north-production-thus-a-58113/
11. Log into the admin (link) with your super user.
12. Verify the following pages load:
    • http://127.0.0.1:8000/post/create/
    • http://127.0.0.1:8000/analytics/

Proceed to Lab 1.