Contributing to Django Documentation, Part 2: Submitting A Patch

Note: This is the second part of a two-part series. The first post is:

Contributing to Django Documentation, Part 1: Generating and Editing Documentation Locally

Whether or not you have a specific piece of documentation you'd like to add, the place to start is always the bug tracker.

• If you want to submit something specific, check to see if someone else has already entered it as a ticket.
• If no one has, go ahead and create the ticket yourself.
• If you don't have specific documentation changes that you'd like to submit, but just want to contribute something, check the bug tracker to see if there's an issue you can help with.

https://code.djangoproject.com/ is where the Django source-code repository, wiki and bug-report system lives.

You could go straight to the bug tracker (https://code.djangoproject.com/query).

But an easier place to start might be the reports page - https://code.djangoproject.com/wiki/Reports - which includes links to several custom queries. From that page, you can get lists for things like 'Tickets marked as "easy"' (for new contributors), 'Unreviewed tickets' or 'Patches that need review' (for intermediate contributors), and so on.

There is also a list of documentation tickets needing attention (and patches):

https://code.djangoproject.com/query?status=!closed&has_patch=0&component=Documentation&order=priority

If you're entering a new ticket (https://code.djangoproject.com/newticket) just use common sense - be clear and descriptive, include specific examples whenever you can. Don't make someone who might be reviewing your ticket work hard to figure out what you mean.

If you find an existing ticket that you think you can handle, just scroll to the bottom and reassign to yourself (at this point you do need to be registered and logged in - you can't take ownership of a ticket as an anonymous user).

And now that ticket is yours. Once you own it, don't let it languish - if you have that ticket in your queue for more than a week or two and don't think you'll be able to make any progress on it, consider relinquishing ownership and put it back into the general pool. On the other hand, if you just feel you need more time, leave a comment to let people know the ticket hasn't been forgotten. People sometimes underestimate how long it takes to write documentation that's clear, concise and accurate.

To see what needs to be included with your submission, take a look at some examples in closed tickets:

https://code.djangoproject.com/query?status=closed&has_patch=1&component=Documentation&order=priority

Patches should be submitted as attachments, not included as plain text in the body of the ticket.

Example: https://code.djangoproject.com/ticket/15236#no1

Note that attachments should be submitted in diff style. A patch can include changes to multiple files - in the example below, the diffs represent changes to two different files:

Before you start making any changes, you'll need to check out the code (if you need them, more detailed instructions are here:

	svn co http://code.djangoproject.com/svn/django/trunk/

It doesn't much matter where you check this code out on your local system - do what makes the most sense for you. If you're only ever planning on editing documentation, then it really doesn't matter - you can alter and regenerate the documentation to your heart's content, independent of the actual code. But if you're also planning on running the code from this checkout (as you would if you eventually submit code patches), be aware that you'll be working with the Django trunk. This is the latest in-development code, so check out and point to it in a place where it won't interfere with any specifically versioned Django releases you might also be running.

Navigate to the docs folder in your checkout:

	cd /path/to/django/checkout/trunk/docs

To make your documentation edits, follow these basic steps:

1. Generate the docs using Sphinx
2. Find the page you want to edit and load it in a browser (e.g., file:///path/to/django/checkout/trunk/docs/_build/html/index.html)
3. Find the file you want to edit and make the change
4. Regenerate the docs
5. Reload the page

For more details refer back to the first post in this series: Contributing to Django Documentation, Part 1: Generating and Editing Documentation Locally

Using the example from the previous post, let's make a change to the docs front page:

	cd /path/to/django/checkout/trunk/docs
	vi index.txt

Once the change is in place, run Sphinx to regenerate the docs:

	[docs]$ make html

Reload your page in the browser (e.g., file:///path/to/django/checkout/trunk/docs/_build/html/index.html). If you're happy with the results, you're ready to build your patch.

Two salient points from the official "Submitting Patches" doc:

• Name the patch file with a .diff extension; this will let the ticket tracker apply correct syntax highlighting, which is quite helpful.
• When creating patches, always run svn diff from the top-level trunk directory - i.e., the one that contains django, docs, tests, AUTHORS, etc. This makes it easy for other people to apply your patches.

I also think it's important to make the patch name meaningful - it's useful to reference the ticket number in the file name:

	cd /path/to/django/checkout/trunk

	svn diff docs/index.txt >> 12485.diff

Now you've got your file - go ahead and attach it to the ticket (under the 'Attachments' block, there's an 'Attach file' button).

Once you've attached your patch, the only other change you need to make to the 'Modify ticket' section of the ticket is to check the 'Has patch:' box

With that flag set, the ticket is ready to be reviewed - you don't need to make any other changes to the ownership or status of the ticket.

From here it's a waiting game. Your patch will be reviewed eventually, so be patient. Someone else in the community will take a look at it (also, be that guy - help out by reviewing other submitted patches), and you may be asked to go through a few cycles of changes to the patch. If/when it is accepted, a core committer will apply your change to the repository.

For more details about the ticket life cycle, check out Ticket triage on the Contributing to Django page.