From 689f325541f236877888e5bd514a58515632d18c Mon Sep 17 00:00:00 2001 From: Tim Schilling Date: Tue, 19 May 2026 14:09:15 -0700 Subject: [PATCH 1/3] Fixed #37111 -- Added sprints quickstart docs page. Adds a documentation page that contains a concise set of guidelines to help new contributors be more effective at sprints or other events with in-person Django contributors. --- docs/internals/contributing/index.txt | 1 + .../contributing/sprint-quickstart.txt | 130 ++++++++++++++++++ 2 files changed, 131 insertions(+) create mode 100644 docs/internals/contributing/sprint-quickstart.txt diff --git a/docs/internals/contributing/index.txt b/docs/internals/contributing/index.txt index ff74c16bb276..cb5c090a4347 100644 --- a/docs/internals/contributing/index.txt +++ b/docs/internals/contributing/index.txt @@ -55,6 +55,7 @@ Our documentation contains guidance for first-time contributors, including: :maxdepth: 1 An overview of the contributing process and what's involved. + If you're at a contribution sprint, start here. Work on the Django framework ============================ diff --git a/docs/internals/contributing/sprint-quickstart.txt b/docs/internals/contributing/sprint-quickstart.txt new file mode 100644 index 000000000000..5c770eb3e8d3 --- /dev/null +++ b/docs/internals/contributing/sprint-quickstart.txt @@ -0,0 +1,130 @@ +======================= +Sprint Quickstart Guide +======================= + +This document outlines the concise guidelines for preparing to contribute to +Django. This should be used during sprints or by people who are more familiar +with contributing to Python open source projects. + +This guide assumes you're familiar with: + +* Git + +* Managing multiple versions of Python + +* Python dependency management, including virtual environments + +* The concept of running tests and building documentation + + +Set up +====== + +Fork the repository, clone your fork to your machine and configure a remote +reference to Django's repository. + +.. code-block:: shell + + $ git clone https://github.com/YourGitHubName/django.git django-repo + $ cd django-repo + $ git remote add upstream https://github.com/django/django.git + +Install the dependencies to run the tests and build the documentation. + +.. code-block:: shell + + $ python -m venv .venv + $ source .venv/bin/activate + $ python -m pip install -e . + $ python -m pip install -r tests/requirements/py3.txt + $ python -m pip install -r docs/requirements.txt + $ # This needs to be >= 3.12 + $ python -V + +Confirm that the version of Python you're using is Python 3.12 or greater. + +Run the tests: + +.. code-block:: shell + + $ ./tests/runtests.py + +If ten or fewer tests fail, you're likely okay to move on. However, keep in +mind if the code you're changing requires changing those tests, you'll need +to fix the underlying issues on your machine first. There are 10,000+ tests +though, so it's unlikely. + +Build the documentation: + +.. code-block:: shell + + $ (cd docs && make html) + + +Finding an issue to work on +=========================== + +Finding a workable ticket is a challenging issue. The ways to get started +are the following: + +* Look at the `easy pickings`_. + +* Use the `vulture method`_. + +The vulture method +------------------ + +This approach to finding tickets is to look for accepted tickets that +haven't been touched in six months or longer. The ideal ticket has a PR +attached to it that has a code review with explicit requests and the author +has not responded in at least six months. + +When you find a stale ticket, make yourself the owner on the ticket with +the "Modify Ticket" button near the bottom of the page. Claim the ticket +by clicking the "assign to" radio button in the "Action" section. Your +username will be filled in the text box by default. + +Assessing issues +---------------- + +When looking over tickets, it's a good idea to keep your search to +tickets that were created in the last five years. An easy way to tell is +by the ticket number. Avoid tickets with an ID of less than 20,000. These +are old for a reason. You're welcome to try, but they will require a high +degree of perseverance. + +Consider using the component filter option in Trac to limit your search +to areas you have used before. If you've used forms in a few Django apps, +consider filtering down to the forms components. Similarly, if you've +never worked with geospatial projects, it's probably wise to avoid +``django.contrib.gis``. + + +Resuming work from someone else's branch +======================================== + +If you're continuing the work from someone else's pull request on GitHub, +things can be tricky. You need to pull their branch, but then push it to +your GitHub repository fork. + +Run the following, but switch ``ThePRNumber`` with the **pull request ID** +and ``TheTicketNumber`` with the **Trac ticket number**. + +.. code-block:: shell + + $ git fetch upstream pull/ThePRNumber/head:ticket_TheTicketNumber + $ git checkout ticket_TheTicketNumber + $ git push origin ticket_TheTicketNumber + +For example, if you're working on PR 8000 which references ticket 123, the +command to run would be: + +.. code-block:: shell + + $ git fetch upstream pull/8000/head:ticket_123 + $ git checkout ticket_123 + $ git push origin ticket_123 + + +.. _easy pickings: https://code.djangoproject.com/query?status=!closed&easy=1 +.. _vulture method: https://youtube.com/shorts/D6QHet5U82U?si=j5M6sy0ufpeGy_iZ From 9ee9b4fd7377c8077d3172619f48924feed10aa5 Mon Sep 17 00:00:00 2001 From: Tim Schilling Date: Mon, 25 May 2026 16:15:14 -0500 Subject: [PATCH 2/3] Minor wording improvements. Co-authored-by: tim-mccurrach <34194722+tim-mccurrach@users.noreply.github.com> --- docs/internals/contributing/sprint-quickstart.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/internals/contributing/sprint-quickstart.txt b/docs/internals/contributing/sprint-quickstart.txt index 5c770eb3e8d3..96bb6622bf2f 100644 --- a/docs/internals/contributing/sprint-quickstart.txt +++ b/docs/internals/contributing/sprint-quickstart.txt @@ -50,7 +50,7 @@ Run the tests: $ ./tests/runtests.py If ten or fewer tests fail, you're likely okay to move on. However, keep in -mind if the code you're changing requires changing those tests, you'll need +mind if the code you're changing requires changing those failing tests, you'll need to fix the underlying issues on your machine first. There are 10,000+ tests though, so it's unlikely. @@ -64,7 +64,7 @@ Build the documentation: Finding an issue to work on =========================== -Finding a workable ticket is a challenging issue. The ways to get started +Finding a workable ticket is a challenging issue. Some ways to get started are the following: * Look at the `easy pickings`_. From a0a1d96e1a495d52a2fcbd8054b85235157ee8fa Mon Sep 17 00:00:00 2001 From: Tim Schilling Date: Mon, 25 May 2026 16:28:38 -0500 Subject: [PATCH 3/3] Reworked finding tickets to work on section This reorders the section and replaces the term "issue" for "ticket" where applicable to be consistent with Django's Trac usage. --- .../contributing/sprint-quickstart.txt | 45 ++++++++++--------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/docs/internals/contributing/sprint-quickstart.txt b/docs/internals/contributing/sprint-quickstart.txt index 96bb6622bf2f..bc872275809c 100644 --- a/docs/internals/contributing/sprint-quickstart.txt +++ b/docs/internals/contributing/sprint-quickstart.txt @@ -61,31 +61,14 @@ Build the documentation: $ (cd docs && make html) -Finding an issue to work on +Finding a ticket to work on =========================== -Finding a workable ticket is a challenging issue. Some ways to get started -are the following: +Finding a workable ticket is a challenging task. It's important +to read this whole section before attempting to find a ticket to work on. -* Look at the `easy pickings`_. - -* Use the `vulture method`_. - -The vulture method ------------------- - -This approach to finding tickets is to look for accepted tickets that -haven't been touched in six months or longer. The ideal ticket has a PR -attached to it that has a code review with explicit requests and the author -has not responded in at least six months. - -When you find a stale ticket, make yourself the owner on the ticket with -the "Modify Ticket" button near the bottom of the page. Claim the ticket -by clicking the "assign to" radio button in the "Action" section. Your -username will be filled in the text box by default. - -Assessing issues ----------------- +Assessing tickets +----------------- When looking over tickets, it's a good idea to keep your search to tickets that were created in the last five years. An easy way to tell is @@ -99,6 +82,24 @@ consider filtering down to the forms components. Similarly, if you've never worked with geospatial projects, it's probably wise to avoid ``django.contrib.gis``. +Methods to find tickets +----------------------- + +Some ways to find a ticket to work on are the following: + +* Look at the `easy pickings`_. + +* Use the `vulture method`_. + +The vulture method is the process where you look for accepted tickets that +haven't been touched in six months or longer. The ideal ticket has a PR +attached to it that has a code review with explicit requests and the author +has not responded in at least six months. + +When you find a stale ticket, make yourself the owner on the ticket with +the "Modify Ticket" button near the bottom of the page. Claim the ticket +by clicking the "assign to" radio button in the "Action" section. Your +username will be filled in the text box by default. Resuming work from someone else's branch ========================================