APPENDIX
Contributing to Django

As with other open source projects, Django relies heavily on community contributions. The community is responsive to those willing to give back to the framework, whether in terms of code, documentation, answers to common questions or even just reporting problems so that others can solve them. And while everyone is encouraged to contribute, there are a few simple expectations that should be followed, which help ensure the contribution will be well received.

As this appendix explains, there are several ways to help out your colleagues, each with its own set of intended situations and expectations to follow.

Reporting a Ticket

For many people, the first step in community contributions is to report a problem with the code as it stands. It doesn't have to be a significant bug; every problem that gets reported—large or small—helps move the framework along.

Issues and feature requests for Django's internal code are kept in an instance of Trac,¹ an open source project management utility. It allows you to browse the source, register new issues, view and comment on existing issues, submit patches, review changes that were made to the codebase and even keep track of any or all of this using automated news feeds.

Perhaps the most important of these features is the ability to report a new ticket for the community to consider. This is often a bug with the code as it stands, but it could be anything from an error in the documentation to a request for a new feature or a suggestion for performance improvements.

If you're entering a bug, just clearly explain the situation, along with any information required to duplicate the problem, what you expect to occur and what actually occurs when you encounter the situation.

Supplying a Patch

If you enter a new issue, or perhaps find an existing one that piques your interest, and you feel comfortable with the subject, you might consider writing a patch to address the issue. The ability of community members to submit patches is an incredibly valuable feature of the open source model, and every patch helps solidify the framework.

__________

Patches in Trac will be applied to trunk, so make sure you've checked out the SVN version of Django and updated it prior to creating the patch. If the patch will be significant in size or scope, you may even want to check out a fresh copy into a new directory, so that any problems with your changes don't adversely impact any of your other Django projects while you get it just right.

When you're confident that you've successfully addressed the problem, generate a file—sometimes called a "diff file" or often just a "diff"—containing your changes. All SVN clients provide a way to create a diff, so check out your client's documentation for details, but if you're using the command-line client, it's quite a simple process.

Then, simply attach the patch to the ticket in Trac, describing what changes you made and what you did to verify that the ticket's primary issue was indeed addressed. It will be reviewed in time by the appropriate developers, and if it seems to do the job well enough and the ticket merits fixing, your patch will help guide the core developers when they update trunk with a fix for the issue.

Please be aware that patches rarely make it from Trac to trunk without any modifications. The core developers are very experienced with Django's internal code, so they may make stylistic changes, add code to address more situations or reduce code to make it more readable or maintainable.

Writing Tests

Whenever a ticket in Trac has a patch for a significant problem, it's expected to also include automated tests that will not only prove that the issue is solved, but help prevent it from resurfacing in the future. Tests are covered in detail in Django's documentation², but they're particularly important for tickets in Trac.

Tests will often be supplied in subsequent patches to a ticket, but may be supplied with the initial patch, if they're easy enough to include. If you're looking at an existing ticket without tests, feel free to supply tests to help the process along. Patches intended solely to add tests for existing features are also appreciated, even if those features are currently working fine; tests will make sure they stay that way.

Writing Documentation

When new features are added to Django, they should be documented so other developers can easily find and understand them. This documentation is usually provided in tickets alongside the patches that implement the new functionality. This way, when the patches are applied to trunk, documentation is included at the same time, so they're always in sync with each other.

Documentation for Django is included in the SVN distribution, in reStructuredText³ format, located in the docs directory. In addition to being in the distribution, these files are used to generate the pages found on the project's Web site. Simply edit the appropriate file to include whatever new or modified features the ticket provides, and attach it to the ticket. If it's being included as part of a new code patch as well, the two can be combined into a single patch, along with tests, if necessary.

__________

As you're writing documentation, be sure to read through what already exists to get a feel for the general style of writing that's expected. Of course, the core developers are always the final authority on what makes it into trunk, though, so any necessary changes in style or structure can be made at that point. The closer you get to the appropriate style, the easier it will be to get the patch ready for check- in to the repository.

Development Sprints

Periodically, the Python community—or a subset of it, like Django—gets a large number of programmers together for sprints. These gatherings are a time for developers to set aside a chunk of time to devote exclusively for giving back to the community. Given the volunteer nature of open source development, time is often precious, so sprints are a way to schedule thousands of man-hours to occur simultaneously, crammed into a period ranging from a few hours to a few days.

Like many Python projects, the Django community schedules sprints periodically as a way to fix issues, commit new features, make decisions and allow developers to get together and have fun working with the code we love. These are often scheduled a few times a year, with several weeks—or even months—of advance notice, allowing people to get time off work or even arrange travel plans to meet in person. For information regarding community-wide sprints, keep an eye on the Django weblog.

For full community-wide sprints, there are often a few locations where local developers can get together in person and communicate directly, with the rest of the development community taking part over the Internet, communicating over IRC. These are usually scheduled by the core developers, and will sometimes coincide with other Python events, such as PyCon,⁴ an annual conference for Python enthusiasts, which dedicates time and space for sprints following its own activities.

Regional sprints, however, may be scheduled by any group of local developers at any time, and typically only involve local developers who can get together in person, and are often called to tackle very specific problems. Regional sprints in the past have focused on such tasks as supporting Oracle databases or geographic information systems. These may be scheduled by any member of the local community, and may even be coordinated with the local Python User Group⁵ to get additional help.

Publishing Code

For individual contributions, everyone is encouraged to publish any code or research they'd like to share with the rest of the community. Any time you've developed something of interest, simply write it up with comments and examples and share.

The key to sharing code or techniques with the community is making sure people know about it. After all, if nobody knows it's out there, nobody can learn from it. There are a few ways to go about this, and they can be used individually or in combination, depending on how heavily you'd like it publicized.

__________

• Publish on the community aggregator⁶ by adding your blog to the list of those it combines. Instructions for doing so are provided on the page.
• Send an email to the django-users mailing list. This type of announcement is typically accompanied by a blog post or software release, with the mailing list email providing a brief overview and a link to more information.
• Submit a bit of code to a community snippet site,⁷ along with a brief description of what it does and how to use it.
• Submit longer code blocks and documentation to the Django development wiki,⁸ where other people can pick up where you leave off and make your code even better.
• Send information about your discovery to the Django podcast,⁹ where it might be discussed on the air and promoted in that way.

These aren't the only ways to share code, so if you have other ideas, feel free to do so however you like, but these are the most commonly used.

Releasing an Application

If you've written an application, beyond just a small snippet of code, the most useful way to share it is to bundle up the code, write some tests and documentation, and release it to the community as a complete application. One option for hosting the application is Google Code, which is favored by many in the community, but any hosting option will suffice.

Details of what it takes to make an application distributable are outside the scope of this book, but an excellent resource is James Bennett's Practical Django Applications (Apress, 2008), which is written with exactly that situation in mind. Once you decide to distribute it, it's a good idea to do so as a single compressed file as well as a freely viewable repository. That way, people who choose to keep up with your latest code can update regularly without having to wait for official releases.

An open repository is also a great way to allow others to observe your development process. A primary benefit of open source is the ability to learn from other developers, but that only works as long as developers are willing to share this type of activity. Many developers also document the decisions they made along the way, often in a blog where they can encourage fruitful discussion.

Another important thing to consider when releasing an application is that developers will likely use it and come to depend on its functionality. As such, they're also likely to submit tickets, supply patches and request new features. Therefore, by releasing it to the public, you're agreeing to continue to support and develop the application for the future. It's generally considered bad form to simply release the application and forget about it.

__________

Also, since Django itself makes sure to keep its trunk version as stable as possible, most Django developers will expect third-party applications to do so as well. This isn't an explicit requirement of releasing an application, but it would be beneficial to make sure that people can update your code regularly without fear of breakage. When backwards-incompatible changes are necessary, just be sure to document them thoroughly.