Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/internals/contributing/index.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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. <new-contributors>
If you're at a contribution sprint, start here. <sprint-quickstart>

Work on the Django framework
============================
Expand Down
131 changes: 131 additions & 0 deletions docs/internals/contributing/sprint-quickstart.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
=======================
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 failing 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 a ticket to work on
===========================

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.

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
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``.

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
========================================

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