diff options
Diffstat (limited to 'parts/django/docs/internals')
| -rw-r--r-- | parts/django/docs/internals/_images/djangotickets.png | bin | 0 -> 52003 bytes | |||
| -rw-r--r-- | parts/django/docs/internals/committers.txt | 344 | ||||
| -rw-r--r-- | parts/django/docs/internals/contributing.txt | 1294 | ||||
| -rw-r--r-- | parts/django/docs/internals/deprecation.txt | 106 | ||||
| -rw-r--r-- | parts/django/docs/internals/documentation.txt | 221 | ||||
| -rw-r--r-- | parts/django/docs/internals/index.txt | 24 | ||||
| -rw-r--r-- | parts/django/docs/internals/release-process.txt | 205 | ||||
| -rw-r--r-- | parts/django/docs/internals/svn.txt | 254 |
8 files changed, 2448 insertions, 0 deletions
diff --git a/parts/django/docs/internals/_images/djangotickets.png b/parts/django/docs/internals/_images/djangotickets.png Binary files differnew file mode 100644 index 0000000..34a2a41 --- /dev/null +++ b/parts/django/docs/internals/_images/djangotickets.png diff --git a/parts/django/docs/internals/committers.txt b/parts/django/docs/internals/committers.txt new file mode 100644 index 0000000..ecda1d5 --- /dev/null +++ b/parts/django/docs/internals/committers.txt @@ -0,0 +1,344 @@ +================= +Django committers +================= + +The original team +================= + +Django originally started at World Online, the Web department of the `Lawrence +Journal-World`_ of Lawrence, Kansas, USA. + +`Adrian Holovaty`_ + Adrian is a Web developer with a background in journalism. He's known in + journalism circles as one of the pioneers of "journalism via computer + programming", and in technical circles as "the guy who invented Django." + + He was lead developer at World Online for 2.5 years, during which time + Django was developed and implemented on World Online's sites. He's now the + leader and founder of EveryBlock_, a "news feed for your block". + + Adrian lives in Chicago, USA. + +`Simon Willison`_ + Simon is a well-respected Web developer from England. He had a one-year + internship at World Online, during which time he and Adrian developed Django + from scratch. The most enthusiastic Brit you'll ever meet, he's passionate + about best practices in Web development and maintains a well-read + `web-development blog`_. + + Simon lives in Brighton, England. + +`Jacob Kaplan-Moss`_ + Jacob is a partner at `Revolution Systems`_ which provides support services + around Django and related open source technologies. A good deal of Jacob's + work time is devoted to working on Django. Jacob previously worked at World + Online, where Django was invented, where he was the lead developer of + Ellington, a commercial Web publishing platform for media companies. + + Jacob lives in Lawrence, Kansas, USA. + +`Wilson Miner`_ + Wilson's design-fu is what makes Django look so nice. He designed the + Web site you're looking at right now, as well as Django's acclaimed admin + interface. Wilson is the designer for EveryBlock_. + + Wilson lives in San Francisco, USA. + +.. _lawrence journal-world: http://ljworld.com/ +.. _adrian holovaty: http://holovaty.com/ +.. _everyblock: http://everyblock.com/ +.. _simon willison: http://simonwillison.net/ +.. _web-development blog: `simon willison`_ +.. _jacob kaplan-moss: http://jacobian.org/ +.. _revolution systems: http://revsys.com/ +.. _wilson miner: http://wilsonminer.com/ + +Current developers +================== + +Currently, Django is led by a team of volunteers from around the globe. + +BDFLs +----- + +Adrian and Jacob are the Co-`Benevolent Dictators for Life`_ of Django. When +"rough consensus and working code" fails, they're the ones who make the tough +decisions. + +.. _Benevolent Dictators for Life: http://en.wikipedia.org/wiki/Benevolent_Dictator_For_Life + +Core developers +--------------- + +These are the folks who have a long history of contributions, a solid track +record of being helpful on the mailing lists, and a proven desire to dedicate +serious time to Django. In return, they've been granted the coveted commit bit, +and have free rein to hack on all parts of Django. + +`Malcolm Tredinnick`_ + Malcolm originally wanted to be a mathematician, somehow ended up a software + developer. He's contributed to many Open Source projects, has served on the + board of the GNOME foundation, and will kick your ass at chess. + + When he's not busy being an International Man of Mystery, Malcolm lives in + Sydney, Australia. + +.. _malcolm tredinnick: http://www.pointy-stick.com/ + +`Russell Keith-Magee`_ + Russell studied physics as an undergraduate, and studied neural networks for + his PhD. His first job was with a startup in the defense industry developing + simulation frameworks. Over time, mostly through work with Django, he's + become more involved in Web development. + + Russell has helped with several major aspects of Django, including a + couple major internal refactorings, creation of the test system, and more. + + Russell lives in the most isolated capital city in the world — Perth, + Australia. + +.. _russell keith-magee: http://cecinestpasun.com/ + +Joseph Kocherhans + Joseph is currently a developer at EveryBlock_, and previously worked for + the Lawrence Journal-World where he built most of the backend for their + Marketplace site. He often disappears for several days into the woods, + attempts to teach himself computational linguistics, and annoys his + neighbors with his Charango_ playing. + + Joseph's first contribution to Django was a series of improvements to the + authorization system leading up to support for pluggable authorization. + Since then, he's worked on the new forms system, its use in the admin, and + many other smaller improvements. + + Joseph lives in Chicago, USA. + +.. _charango: http://en.wikipedia.org/wiki/Charango + +`Luke Plant`_ + At University Luke studied physics and Materials Science and also + met `Michael Meeks`_ who introduced him to Linux and Open Source, + re-igniting an interest in programming. Since then he has + contributed to a number of Open Source projects and worked + professionally as a developer. + + Luke has contributed many excellent improvements to Django, + including database-level improvements, the CSRF middleware and + many unit tests. + + Luke currently works for a church in Bradford, UK, and part-time + as a freelance developer. + +.. _luke plant: http://lukeplant.me.uk/ +.. _michael meeks: http://en.wikipedia.org/wiki/Michael_Meeks_(software) + +`Brian Rosner`_ + Brian is currently the tech lead at Eldarion_ managing and developing + Django / Pinax_ based Web sites. He enjoys learning more about programming + languages and system architectures and contributing to open source + projects. Brian is the host of the `Django Dose`_ podcasts. + + Brian helped immensely in getting Django's "newforms-admin" branch finished + in time for Django 1.0; he's now a full committer, continuing to improve on + the admin and forms system. + + Brian lives in Denver, Colorado, USA. + +.. _brian rosner: http://oebfare.com/ +.. _eldarion: http://eldarion.com/ +.. _django dose: http://djangodose.com/ + +`Gary Wilson`_ + Gary starting contributing patches to Django in 2006 while developing Web + applications for `The University of Texas`_ (UT). Since, he has made + contributions to the e-mail and forms systems, as well as many other + improvements and code cleanups throughout the code base. + + Gary is currently a developer and software engineering graduate student at + UT, where his dedication to spreading the ways of Python and Django never + ceases. + + Gary lives in Austin, Texas, USA. + +.. _Gary Wilson: http://gdub.wordpress.com/ +.. _The University of Texas: http://www.utexas.edu/ + +Justin Bronn + Justin Bronn is a computer scientist and attorney specializing + in legal topics related to intellectual property and spatial law. + + In 2007, Justin began developing ``django.contrib.gis`` in a branch, + a.k.a. GeoDjango_, which was merged in time for Django 1.0. While + implementing GeoDjango, Justin obtained a deep knowledge of Django's + internals including the ORM, the admin, and Oracle support. + + Justin lives in Houston, Texas. + +.. _GeoDjango: http://geodjango.org/ + +Karen Tracey + Karen has a background in distributed operating systems (graduate school), + communications software (industry) and crossword puzzle construction + (freelance). The last of these brought her to Django, in late 2006, when + she set out to put a Web front-end on her crossword puzzle database. + That done, she stuck around in the community answering questions, debugging + problems, etc. -- because coding puzzles are as much fun as word puzzles. + + Karen lives in Apex, NC, USA. + +`Jannis Leidel`_ + Jannis graduated in media design from `Bauhaus-University Weimar`_, + is the author of a number of pluggable Django apps and likes to + contribute to Open Source projects like Pinax_. He currently works as + a freelance Web developer and designer. + + Jannis lives in Berlin, Germany. + +.. _Jannis Leidel: http://jezdez.com/ +.. _Bauhaus-University Weimar: http://www.uni-weimar.de/ +.. _pinax: http://pinaxproject.com/ + +`James Tauber`_ + James is the lead developer of Pinax_ and the CEO and founder of + Eldarion_. He has been doing open source software since 1993, Python + since 1998 and Django since 2006. He serves on the board of the Python + Software Foundation and is currently on a leave of absence from a PhD in + linguistics. + + James currently lives in Boston, MA, USA but originally hails from + Perth, Western Australia where he attended the same high school as + Russell Keith-Magee. + +.. _James Tauber: http://jtauber.com/ + +`Alex Gaynor`_ + Alex is a student at Rensselaer Polytechnic Institute, and is also an + independent contractor. He found Django in 2007 and has been addicted ever + since he found out you don't need to write out your forms by hand. He has + a small obsession with compilers. He's contributed to the ORM, forms, + admin, and other components of Django. + + Alex lives in Chicago, IL, but spends most of his time in Troy, NY. + +.. _Alex Gaynor: http://alexgaynor.net + +`Andrew Godwin`_ + Andrew is a freelance Python developer and tinkerer, and has been + developing against Django since 2007. He graduated from Oxford University + with a degree in Computer Science, and has become most well known + in the Django community for his work on South, the schema migrations + library. + + Andrew lives in London, UK. + +.. _Andrew Godwin: http://www.aeracode.org/ + +`Carl Meyer`_ + Carl has been working with Django since 2007 (long enough to remember + queryset-refactor, but not magic-removal), and works as a freelance + developer with OddBird_ and Eldarion_. He became a Django contributor by + accident, because fixing bugs is more interesting than working around + them. + + Carl lives in Elkhart, IN, USA. + +.. _Carl Meyer: http://www.oddbird.net/about/#hcard-carl +.. _OddBird: http://www.oddbird.net/ + +Ramiro Morales + Ramiro has been reading Django source code and submitting patches since + mid-2006 after researching for a Python Web tool with matching awesomeness + and being pointed to it by an old ninja. + + A software developer in the electronic transactions industry, he is a + living proof of the fact that anyone with enough enthusiasm can contribute + to Django, learning a lot and having fun in the process. + + Ramiro lives in Córdoba, Argentina. + +`Chris Beaven`_ + Chris has been submitting patches and suggesting crazy ideas for Django + since early 2006. An advocate for community involvement and a long-term + triager, he is still often found answering questions in the #django IRC + channel. + + Chris lives in Napier, New Zealand (adding to the pool of Oceanic core + developers). He works remotely as a developer for `Lincoln Loop`_. + +.. _Chris Beaven: http://smileychris.com/ +.. _Lincoln Loop: http://lincolnloop.com/ + +Specialists +----------- + +`James Bennett`_ + James is Django's release manager; he also contributes to the documentation. + + James came to Web development from philosophy when he discovered + that programmers get to argue just as much while collecting much + better pay. He lives in Lawrence, Kansas, where he works for the + Journal-World developing Ellington. He `keeps a blog`_, has + written a `book on Django`_, and enjoys fine port and talking to + his car. + +.. _james bennett: http://b-list.org/ +.. _keeps a blog: `james bennett`_ +.. _book on Django: http://www.amazon.com/dp/1590599969/?tag=djangoproject-20 + +Ian Kelly + Ian is responsible for Django's support for Oracle. + +Matt Boersma + Matt is also responsible for Django's Oracle support. + +Jeremy Dunck + Jeremy is the lead developer of Pegasus News, a personalized local site based + in Dallas, Texas. An early contributor to Greasemonkey and Django, he sees + technology as a tool for communication and access to knowledge. + + Jeremy helped kick off GeoDjango development, and is mostly responsible for + the serious speed improvements that signals received in Django 1.0. + + Jeremy lives in Dallas, Texas, USA. + +`Simon Meers`_ + Simon discovered Django 0.96 during his Computer Science PhD research and + has been developing with it full-time ever since. His core code + contributions are mostly in Django's admin application. He is also helping + to improve Django's documentation. + + Simon works as a freelance developer based in Wollongong, Australia. + +.. _simon meers: http://simonmeers.com/ + +`Gabriel Hurley`_ + Gabriel has been working with Django since 2008, shortly after the 1.0 + release. Convinced by his business partner that Python and Django were the + right direction for the company, he couldn't have been more happy with the + decision. His contributions range across many areas in Django, but years of + copy-editing and an eye for detail lead him to be particularly at home + while working on Django's documentation. + + Gabriel works as a web developer in Berkeley, CA, USA. + +.. _gabriel hurley: http://strikeawe.com/ + +Tim Graham + When exploring Web frameworks for an independent study project in the fall + of 2008, Tim discovered Django and was lured to it by the documentation. + He enjoys contributing to the docs because they're awesome. + + Tim works as a software engineer and lives in Philadelphia, PA, USA. + +Developers Emeritus +=================== + +Georg "Hugo" Bauer + Georg created Django's internationalization system, managed i18n + contributions and made a ton of excellent tweaks, feature additions and bug + fixes. + +Robert Wittams + Robert was responsible for the *first* refactoring of Django's admin + application to allow for easier reuse and has made a ton of + excellent tweaks, feature additions and bug fixes. diff --git a/parts/django/docs/internals/contributing.txt b/parts/django/docs/internals/contributing.txt new file mode 100644 index 0000000..fd0e48b --- /dev/null +++ b/parts/django/docs/internals/contributing.txt @@ -0,0 +1,1294 @@ +====================== +Contributing to Django +====================== + +If you think working *with* Django is fun, wait until you start working *on* it. +We're passionate about helping Django users make the jump to contributing members +of the community, so there are many ways you can help Django's development: + + * Blog about Django. We syndicate all the Django blogs we know about on + the `community page`_; contact jacob@jacobian.org if you've got a blog + you'd like to see on that page. + + * Report bugs and request features in our `ticket tracker`_. Please read + `Reporting bugs`_, below, for the details on how we like our bug reports + served up. + + * Submit patches for new and/or fixed behavior. Please read `Submitting + patches`_, below, for details on how to submit a patch. If you're looking + for an easy way to start contributing to Django have a look at the + `easy-pickings`_ tickets. + + * Join the `django-developers`_ mailing list and share your ideas for how + to improve Django. We're always open to suggestions, although we're + likely to be skeptical of large-scale suggestions without some code to + back it up. + + * Triage patches that have been submitted by other users. Please read + `Ticket triage`_ below, for details on the triage process. + +That's all you need to know if you'd like to join the Django development +community. The rest of this document describes the details of how our community +works and how it handles bugs, mailing lists, and all the other minutiae of +Django development. + +.. _reporting-bugs: + +Reporting bugs +============== + +Well-written bug reports are *incredibly* helpful. However, there's a certain +amount of overhead involved in working with any bug tracking system, so your +help in keeping our ticket tracker as useful as possible is appreciated. In +particular: + + * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might be a well-known question. + + * **Do** `search the tracker`_ to see if your issue has already been filed. + + * **Do** ask on `django-users`_ *first* if you're not sure if what you're + seeing is a bug. + + * **Do** write complete, reproducible, specific bug reports. Include as + much information as you possibly can, complete with code snippets, test + cases, etc. This means including a clear, concise description of the + problem, and a clear set of instructions for replicating the problem. + A minimal example that illustrates the bug in a nice small test case + is the best possible bug report. + + * **Don't** use the ticket system to ask support questions. Use the + `django-users`_ list, or the `#django`_ IRC channel for that. + + * **Don't** use the ticket system to make large-scale feature requests. + We like to discuss any big changes to Django's core on the `django-developers`_ + list before actually working on them. + + * **Don't** reopen issues that have been marked "wontfix". This mark means + that the decision has been made that we can't or won't fix this particular + issue. If you're not sure why, please ask on `django-developers`_. + + * **Don't** use the ticket tracker for lengthy discussions, because they're + likely to get lost. If a particular ticket is controversial, please move + discussion to `django-developers`_. + + * **Don't** post to django-developers just to announce that you have filed + a bug report. All the tickets are mailed to another list + (`django-updates`_), which is tracked by developers and triagers, so we + see them as they are filed. + +.. _django-updates: http://groups.google.com/group/django-updates + +.. _reporting-security-issues: + +Reporting security issues +========================= + +Report security issues to security@djangoproject.com. This is a private list +only open to long-time, highly trusted Django developers, and its archives are +not publicly readable. + +In the event of a confirmed vulnerability in Django itself, we will take the +following actions: + + * Acknowledge to the reporter that we've received the report and that a fix + is forthcoming. We'll give a rough timeline and ask the reporter to keep + the issue confidential until we announce it. + + * Halt all other development as long as is needed to develop a fix, including + patches against the current and two previous releases. + + * Determine a go-public date for announcing the vulnerability and the fix. + To try to mitigate a possible "arms race" between those applying the patch + and those trying to exploit the hole, we will not announce security + problems immediately. + + * Pre-notify everyone we know to be running the affected version(s) of + Django. We will send these notifications through private e-mail which will + include documentation of the vulnerability, links to the relevant patch(es), + and a request to keep the vulnerability confidential until the official + go-public date. + + * Publicly announce the vulnerability and the fix on the pre-determined + go-public date. This will probably mean a new release of Django, but + in some cases it may simply be patches against current releases. + +Submitting patches +================== + +We're always grateful for patches to Django's code. Indeed, bug reports with +associated patches will get fixed *far* more quickly than those without patches. + +"Claiming" tickets +------------------ + +In an open-source project with hundreds of contributors around the world, it's +important to manage communication efficiently so that work doesn't get +duplicated and contributors can be as effective as possible. Hence, our policy +is for contributors to "claim" tickets in order to let other developers know +that a particular bug or feature is being worked on. + +If you have identified a contribution you want to make and you're capable of +fixing it (as measured by your coding ability, knowledge of Django internals +and time availability), claim it by following these steps: + + * `Create an account`_ to use in our ticket system. + * If a ticket for this issue doesn't exist yet, create one in our + `ticket tracker`_. + * If a ticket for this issue already exists, make sure nobody else has + claimed it. To do this, look at the "Assigned to" section of the ticket. + If it's assigned to "nobody," then it's available to be claimed. + Otherwise, somebody else is working on this ticket, and you either find + another bug/feature to work on, or contact the developer working on the + ticket to offer your help. + * Log into your account, if you haven't already, by clicking "Login" in the + upper right of the ticket page. + * Claim the ticket by clicking the radio button next to "Accept ticket" + near the bottom of the page, then clicking "Submit changes." + +If you have an account but have forgotten your password, you can reset it +using the `password reset page`_. + +.. _Create an account: http://www.djangoproject.com/accounts/register/ +.. _password reset page: http://www.djangoproject.com/accounts/password/reset/ + +Ticket claimers' responsibility +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you've claimed a ticket, you have a responsibility to work on that ticket +in a reasonably timely fashion. If you don't have time to work on it, either +unclaim it or don't claim it in the first place! + +Ticket triagers go through the list of claimed tickets from time to +time, checking whether any progress has been made. If there's no sign of +progress on a particular claimed ticket for a week or two, a triager may ask +you to relinquish the ticket claim so that it's no longer monopolized and +somebody else can claim it. + +If you've claimed a ticket and it's taking a long time (days or weeks) to code, +keep everybody updated by posting comments on the ticket. If you don't provide +regular updates, and you don't respond to a request for a progress report, +your claim on the ticket may be revoked. As always, more communication is +better than less communication! + +Which tickets should be claimed? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Of course, going through the steps of claiming tickets is overkill in some +cases. In the case of small changes, such as typos in the documentation or +small bugs that will only take a few minutes to fix, you don't need to jump +through the hoops of claiming tickets. Just submit your patch and be done with +it. + +Patch style +----------- + + * Make sure your code matches our `coding style`_. + + * Submit patches in the format returned by the ``svn diff`` command. + An exception is for code changes that are described more clearly in plain + English than in code. Indentation is the most common example; it's hard to + read patches when the only difference in code is that it's indented. + + Patches in ``git diff`` format are also acceptable. + + * 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. + + * Attach patches to a ticket in the `ticket tracker`_, using the "attach file" + button. Please *don't* put the patch in the ticket description or comment + unless it's a single line patch. + + * Name the patch file with a ``.diff`` extension; this will let the ticket + tracker apply correct syntax highlighting, which is quite helpful. + + * Check the "Has patch" box on the ticket details. This will make it + obvious that the ticket includes a patch, and it will add the ticket to + the `list of tickets with patches`_. + + * The code required to fix a problem or add a feature is an essential part + of a patch, but it is not the only part. A good patch should also include + a regression test to validate the behavior that has been fixed (and prevent + the problem from arising again). + + * If the code associated with a patch adds a new feature, or modifies behavior + of an existing feature, the patch should also contain documentation. + +Non-trivial patches +------------------- + +A "non-trivial" patch is one that is more than a simple bug fix. It's a patch +that introduces Django functionality and makes some sort of design decision. + +If you provide a non-trivial patch, include evidence that alternatives have +been discussed on `django-developers`_. If you're not sure whether your patch +should be considered non-trivial, just ask. + +Ticket triage +============= + +Unfortunately, not all bug reports in the `ticket tracker`_ provide all +the `required details`_. A number of tickets have patches, but those patches +don't meet all the requirements of a `good patch`_. + +One way to help out is to *triage* bugs that have been reported by other +users. A couple of dedicated volunteers work on this regularly, but more help +is always appreciated. + +Most of the workflow is based around the concept of a ticket's "triage stage". +This stage describes where in its lifetime a given ticket is at any time. +Along with a handful of flags, this field easily tells us what and who each +ticket is waiting on. + +Since a picture is worth a thousand words, let's start there: + +.. image:: _images/djangotickets.png + :height: 451 + :width: 590 + :alt: Django's ticket workflow + +We've got two official roles here: + + * Core developers: people with commit access who make the big decisions + and write the bulk of the code. + + * Ticket triagers: trusted community members with a proven history of + working with the Django community. As a result of this history, they + have been entrusted by the core developers to make some of the smaller + decisions about tickets. + +Second, note the five triage stages: + + 1. A ticket starts as "Unreviewed", meaning that nobody has examined + the ticket. + + 2. "Design decision needed" means "this concept requires a design + decision," which should be discussed either in the ticket comments or on + `django-developers`_. The "Design decision needed" step will generally + only be used for feature requests. It can also be used for issues + that *might* be bugs, depending on opinion or interpretation. Obvious + bugs (such as crashes, incorrect query results, or non-compliance with a + standard) skip this step and move straight to "Accepted". + + 3. Once a ticket is ruled to be approved for fixing, it's moved into the + "Accepted" stage. This stage is where all the real work gets done. + + 4. In some cases, a ticket might get moved to the "Someday/Maybe" state. + This means the ticket is an enhancement request that we might consider + adding to the framework if an excellent patch is submitted. These + tickets are not a high priority. + + 5. If a ticket has an associated patch (see below), a triager will review + the patch. If the patch is complete, it'll be marked as "ready for + checkin" so that a core developer knows to review and check in the + patches. + +The second part of this workflow involves a set of flags the describe what the +ticket has or needs in order to be "ready for checkin": + + "Has patch" + This means the ticket has an associated patch_. These will be + reviewed by the triage team to see if the patch is "good". + + "Needs documentation" + This flag is used for tickets with patches that need associated + documentation. Complete documentation of features is a prerequisite + before we can check a fix into the codebase. + + "Needs tests" + This flags the patch as needing associated unit tests. Again, this is a + required part of a valid patch. + + "Patch needs improvement" + This flag means that although the ticket *has* a patch, it's not quite + ready for checkin. This could mean the patch no longer applies + cleanly, or that the code doesn't live up to our standards. + +A ticket can be resolved in a number of ways: + + "fixed" + Used by one of the core developers once a patch has been rolled into + Django and the issue is fixed. + + "invalid" + Used if the ticket is found to be incorrect. This means that the + issue in the ticket is actually the result of a user error, or + describes a problem with something other than Django, or isn't + a bug report or feature request at all (for example, some new users + submit support queries as tickets). + + "wontfix" + Used when a core developer decides that this request is not + appropriate for consideration in Django. This is usually chosen after + discussion in the ``django-developers`` mailing list, and you should + feel free to join in when it's something you care about. + + "duplicate" + Used when another ticket covers the same issue. By closing duplicate + tickets, we keep all the discussion in one place, which helps everyone. + + "worksforme" + Used when the ticket doesn't contain enough detail to replicate + the original bug. + +If you believe that the ticket was closed in error -- because you're +still having the issue, or it's popped up somewhere else, or the triagers have +-- made a mistake, please reopen the ticket and tell us why. Please do not +reopen tickets that have been marked as "wontfix" by core developers. + +.. _required details: `Reporting bugs`_ +.. _good patch: `Patch style`_ +.. _patch: `Submitting patches`_ + +Triage by the general community +------------------------------- + +Although the core developers and ticket triagers make the big decisions in +the ticket triage process, there's also a lot that general community +members can do to help the triage process. In particular, you can help out by: + + * Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate." + + * Promoting "Unreviewed" tickets to "Design decision needed" if a design + decision needs to be made, or "Accepted" in case of obvious bugs. + + * Correcting the "Needs tests", "Needs documentation", or "Has patch" flags + for tickets where they are incorrectly set. + + * Adding the `easy-pickings`_ keyword to tickets that are small and + relatively straightforward. + + * Checking that old tickets are still valid. If a ticket hasn't seen + any activity in a long time, it's possible that the problem has been + fixed but the ticket hasn't yet been closed. + + * Contacting the owners of tickets that have been claimed but have not seen + any recent activity. If the owner doesn't respond after a week or so, + remove the owner's claim on the ticket. + + * Identifying trends and themes in the tickets. If there a lot of bug reports + about a particular part of Django, it may indicate we should consider + refactoring that part of the code. If a trend is emerging, you should + raise it for discussion (referencing the relevant tickets) on + `django-developers`_. + +However, we do ask the following of all general community members working in +the ticket database: + + * Please **don't** close tickets as "wontfix." The core developers will + make the final determination of the fate of a ticket, usually after + consultation with the community. + + * Please **don't** promote tickets to "Ready for checkin" unless they are + *trivial* changes -- for example, spelling mistakes or broken links in + documentation. + + * Please **don't** reverse a decision that has been made by a core + developer. If you disagree with a discussion that has been made, + please post a message to `django-developers`_. + + * Please be conservative in your actions. If you're unsure if you should + be making a change, don't make the change -- leave a comment with your + concerns on the ticket, or post a message to `django-developers`_. + +.. _contributing-translations: + +Submitting and maintaining translations +======================================= + +Various parts of Django, such as the admin site and validation error messages, +are internationalized. This means they display different text depending on a +user's language setting. For this, Django uses the same internationalization +infrastructure available to Django applications described in the +:doc:`i18n documentation</topics/i18n/index>`. + +These translations are contributed by Django users worldwide. If you find an +incorrect translation, or if you'd like to add a language that isn't yet +translated, here's what to do: + + * Join the `Django i18n mailing list`_ and introduce yourself. + + * Make sure you read the notes about :ref:`specialties-of-django-i18n`. + + * Create translations using the methods described in the + :doc:`localization documentation </topics/i18n/localization>`. For this + you will use the ``django-admin.py makemessages`` tool. In this + particular case it should be run from the top-level ``django`` directory + of the Django source tree. + + The script runs over the entire Django source tree and pulls out all + strings marked for translation. It creates (or updates) a message file in + the directory ``conf/locale`` (for example for ``pt_BR``, the file will be + ``conf/locale/pt_BR/LC_MESSAGES/django.po``). + + * Make sure that ``django-admin.py compilemessages -l <lang>`` runs without + producing any warnings. + + * Repeat the last two steps for the ``djangojs`` domain (by appending the + ``-d djangojs`` command line option to the ``django-admin.py`` + invocations). + + * Optionally, review and update the ``conf/locale/<locale>/formats.py`` + file to describe the date, time and numbers formatting particularities of + your locale. See :ref:`format-localization` for details. + + * Create a diff against the current Subversion trunk. + + * Open a ticket in Django's ticket system, set its ``Component`` field to + ``Translations``, and attach the patch to it. + +.. _Django i18n mailing list: http://groups.google.com/group/django-i18n/ + +Submitting javascript patches +============================= + +.. versionadded:: 1.2 + +Django's admin system leverages the jQuery framework to increase the +capabilities of the admin interface. In conjunction, there is an emphasis on +admin javascript performance and minimizing overall admin media file size. +Serving compressed or "minified" versions of javascript files is considered +best practice in this regard. + +To that end, patches for javascript files should include both the original +code for future development (e.g. "foo.js"), and a compressed version for +production use (e.g. "foo.min.js"). Any links to the file in the codebase +should point to the compressed version. + +To simplify the process of providing optimized javascript code, Django +includes a handy script which should be used to create a "minified" version. +This script is located at ``/contrib/admin/media/js/compress.py``. + +Behind the scenes, ``compress.py`` is a front-end for Google's +`Closure Compiler`_ which is written in Java. However, the Closure Compiler +library is not bundled with Django directly, so those wishing to contribute +complete javascript patches will need to download and install the library +independently. + +The Closure Compiler library requires Java version 6 or higher (Java 1.6 or +higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with Java +1.6 by default, so it may be necessary to upgrade your Java installation before +the tool will be functional. Also note that even after upgrading Java, the +default `/usr/bin/java` command may remain linked to the previous Java +binary, so relinking that command may be necessary as well. + +Please don't forget to run ``compress.py`` and include the ``diff`` of the +minified scripts when submitting patches for Django's javascript. + +.. _Closure Compiler: http://code.google.com/closure/compiler/ + +Django conventions +================== + +Various Django-specific code issues are detailed in this section. + +Use of ``django.conf.settings`` +------------------------------- + +Modules should not in general use settings stored in ``django.conf.settings`` at +the top level (i.e. evaluated when the module is imported). The explanation for +this is as follows: + +Manual configuration of settings (i.e. not relying on the +``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as +follows:: + + from django.conf import settings + + settings.configure({}, SOME_SETTING='foo') + +However, if any setting is accessed before the ``settings.configure`` line, this +will not work. (Internally, ``settings`` is a ``LazyObject`` which configures +itself automatically when the settings are accessed if it has not already been +configured). + +So, if there is a module containing some code as follows:: + + from django.conf import settings + from django.core.urlresolvers import get_callable + + default_foo_view = get_callable(settings.FOO_VIEW) + +...then importing this module will cause the settings object to be configured. +That means that the ability for third parties to import the module at the top +level is incompatible with the ability to configure the settings object +manually, or makes it very difficult in some circumstances. + +Instead of the above code, a level of laziness or indirection must be used, such +as :class:`django.utils.functional.LazyObject`, :func:`django.utils.functional.lazy` or +``lambda``. + +Coding style +============ + +Please follow these coding standards when writing code for inclusion in Django: + + * Unless otherwise specified, follow :pep:`8`. + + You could use a tool like `pep8.py`_ to check for some problems in this + area, but remember that PEP 8 is only a guide, so respect the style of + the surrounding code as a primary goal. + + * Use four spaces for indentation. + + * Use underscores, not camelCase, for variable, function and method names + (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``). + + * Use ``InitialCaps`` for class names (or for factory functions that + return classes). + + * Mark all strings for internationalization; see the :doc:`i18n + documentation </topics/i18n/index>` for details. + + * In docstrings, use "action words" such as:: + + def foo(): + """ + Calculates something and returns the result. + """ + pass + + Here's an example of what not to do:: + + def foo(): + """ + Calculate something and return the result. + """ + pass + + * Please don't put your name in the code you contribute. Our policy is to + keep contributors' names in the ``AUTHORS`` file distributed with Django + -- not scattered throughout the codebase itself. Feel free to include a + change to the ``AUTHORS`` file in your patch if you make more than a + single trivial change. + +Template style +-------------- + + * In Django template code, put one (and only one) space between the curly + brackets and the tag contents. + + Do this: + + .. code-block:: html+django + + {{ foo }} + + Don't do this: + + .. code-block:: html+django + + {{foo}} + +View style +---------- + + * In Django views, the first parameter in a view function should be called + ``request``. + + Do this:: + + def my_view(request, foo): + # ... + + Don't do this:: + + def my_view(req, foo): + # ... + +Model style +----------- + + * Field names should be all lowercase, using underscores instead of + camelCase. + + Do this:: + + class Person(models.Model): + first_name = models.CharField(max_length=20) + last_name = models.CharField(max_length=40) + + Don't do this:: + + class Person(models.Model): + FirstName = models.CharField(max_length=20) + Last_Name = models.CharField(max_length=40) + + * The ``class Meta`` should appear *after* the fields are defined, with + a single blank line separating the fields and the class definition. + + Do this:: + + class Person(models.Model): + first_name = models.CharField(max_length=20) + last_name = models.CharField(max_length=40) + + class Meta: + verbose_name_plural = 'people' + + Don't do this:: + + class Person(models.Model): + first_name = models.CharField(max_length=20) + last_name = models.CharField(max_length=40) + class Meta: + verbose_name_plural = 'people' + + Don't do this, either:: + + class Person(models.Model): + class Meta: + verbose_name_plural = 'people' + + first_name = models.CharField(max_length=20) + last_name = models.CharField(max_length=40) + + * The order of model inner classes and standard methods should be as + follows (noting that these are not all required): + + * All database fields + * Custom manager attributes + * ``class Meta`` + * ``def __unicode__()`` + * ``def __str__()`` + * ``def save()`` + * ``def get_absolute_url()`` + * Any custom methods + + * If ``choices`` is defined for a given model field, define the choices as + a tuple of tuples, with an all-uppercase name, either near the top of the + model module or just above the model class. Example:: + + GENDER_CHOICES = ( + ('M', 'Male'), + ('F', 'Female'), + ) + +Documentation style +=================== + +We place a high importance on consistency and readability of documentation. +(After all, Django was created in a journalism environment!) + +How to document new features +---------------------------- + +We treat our documentation like we treat our code: we aim to improve it as +often as possible. This section explains how writers can craft their +documentation changes in the most useful and least error-prone ways. + +Documentation changes come in two forms: + + * General improvements -- Typo corrections, error fixes and better + explanations through clearer writing and more examples. + + * New features -- Documentation of features that have been added to the + framework since the last release. + +Our policy is: + + **All documentation of new features should be written in a way that clearly + designates the features are only available in the Django development + version. Assume documentation readers are using the latest release, not the + development version.** + +Our preferred way for marking new features is by prefacing the features' +documentation with: ".. versionadded:: X.Y", followed by an optional one line +comment and a mandatory blank line. + +General improvements, or other changes to the APIs that should be emphasized +should use the ".. versionchanged:: X.Y" directive (with the same format as the +``versionadded`` mentioned above. + +There's a full page of information about the :doc:`Django documentation +system </internals/documentation>` that you should read prior to working on the +documentation. + +Guidelines for reST files +------------------------- + +These guidelines regulate the format of our reST documentation: + + * In section titles, capitalize only initial words and proper nouns. + + * Wrap the documentation at 80 characters wide, unless a code example + is significantly less readable when split over two lines, or for another + good reason. + +Commonly used terms +------------------- + +Here are some style guidelines on commonly used terms throughout the +documentation: + + * **Django** -- when referring to the framework, capitalize Django. It is + lowercase only in Python code and in the djangoproject.com logo. + + * **e-mail** -- it has a hyphen. + + * **MySQL** + + * **PostgreSQL** + + * **Python** -- when referring to the language, capitalize Python. + + * **realize**, **customize**, **initialize**, etc. -- use the American + "ize" suffix, not "ise." + + * **SQLite** + + * **subclass** -- it's a single word without a hyphen, both as a verb + ("subclass that model") and as a noun ("create a subclass"). + + * **Web**, **World Wide Web**, **the Web** -- note Web is always + capitalized when referring to the World Wide Web. + + * **Web site** -- use two words, with Web capitalized. + +Django-specific terminology +--------------------------- + + * **model** -- it's not capitalized. + + * **template** -- it's not capitalized. + + * **URLconf** -- use three capitalized letters, with no space before + "conf." + + * **view** -- it's not capitalized. + +Committing code +=============== + +Please follow these guidelines when committing code to Django's Subversion +repository: + + * For any medium-to-big changes, where "medium-to-big" is according to your + judgment, please bring things up on the `django-developers`_ mailing list + before making the change. + + If you bring something up on `django-developers`_ and nobody responds, + please don't take that to mean your idea is great and should be + implemented immediately because nobody contested it. Django's lead + developers don't have a lot of time to read mailing-list discussions + immediately, so you may have to wait a couple of days before getting a + response. + + * Write detailed commit messages in the past tense, not present tense. + + * Good: "Fixed Unicode bug in RSS API." + * Bad: "Fixes Unicode bug in RSS API." + * Bad: "Fixing Unicode bug in RSS API." + + * For commits to a branch, prefix the commit message with the branch name. + For example: "magic-removal: Added support for mind reading." + + * Limit commits to the most granular change that makes sense. This means, + use frequent small commits rather than infrequent large commits. For + example, if implementing feature X requires a small change to library Y, + first commit the change to library Y, then commit feature X in a separate + commit. This goes a *long way* in helping all core Django developers + follow your changes. + + * Separate bug fixes from feature changes. + + Bug fixes need to be added to the current bugfix branch (e.g. the + ``1.0.X`` branch) as well as the current trunk. + + * If your commit closes a ticket in the Django `ticket tracker`_, begin + your commit message with the text "Fixed #abc", where "abc" is the number + of the ticket your commit fixes. Example: "Fixed #123 -- Added support + for foo". We've rigged Subversion and Trac so that any commit message + in that format will automatically close the referenced ticket and post a + comment to it with the full commit message. + + If your commit closes a ticket and is in a branch, use the branch name + first, then the "Fixed #abc." For example: + "magic-removal: Fixed #123 -- Added whizbang feature." + + For the curious: We're using a `Trac post-commit hook`_ for this. + + .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook + + * If your commit references a ticket in the Django `ticket tracker`_ but + does *not* close the ticket, include the phrase "Refs #abc", where "abc" + is the number of the ticket your commit references. We've rigged + Subversion and Trac so that any commit message in that format will + automatically post a comment to the appropriate ticket. + +Reverting commits +----------------- + +Nobody's perfect; mistakes will be committed. When a mistaken commit is +discovered, please follow these guidelines: + + * Try very hard to ensure that mistakes don't happen. Just because we + have a reversion policy doesn't relax your responsibility to aim for + the highest quality possible. Really: double-check your work before + you commit it in the first place! + + * If possible, have the original author revert his/her own commit. + + * Don't revert another author's changes without permission from the + original author. + + * If the original author can't be reached (within a reasonable amount + of time -- a day or so) and the problem is severe -- crashing bug, + major test failures, etc -- then ask for objections on django-dev + then revert if there are none. + + * If the problem is small (a feature commit after feature freeze, + say), wait it out. + + * If there's a disagreement between the committer and the + reverter-to-be then try to work it out on the `django-developers`_ + mailing list. If an agreement can't be reached then it should + be put to a vote. + + * If the commit introduced a confirmed, disclosed security + vulnerability then the commit may be reverted immediately without + permission from anyone. + + * The release branch maintainer may back out commits to the release + branch without permission if the commit breaks the release branch. + +.. _unit-tests: + +Unit tests +========== + +Django comes with a test suite of its own, in the ``tests`` directory of the +Django tarball. It's our policy to make sure all tests pass at all times. + +The tests cover: + + * Models and the database API (``tests/modeltests/``). + * Everything else in core Django code (``tests/regressiontests``) + * Contrib apps (``django/contrib/<contribapp>/tests``, see below) + +We appreciate any and all contributions to the test suite! + +The Django tests all use the testing infrastructure that ships with Django for +testing applications. See :doc:`Testing Django applications </topics/testing>` +for an explanation of how to write new tests. + +.. _running-unit-tests: + +Running the unit tests +---------------------- + +To run the tests, ``cd`` to the ``tests/`` directory and type: + +.. code-block:: bash + + ./runtests.py --settings=path.to.django.settings + +Yes, the unit tests need a settings module, but only for database connection +info. Your :setting:`DATABASES` setting needs to define two databases: + + * A ``default`` database. This database should use the backend that + you want to use for primary testing + + * A database with the alias ``other``. The ``other`` database is + used to establish that queries can be directed to different + databases. As a result, this database can use any backend you + want. It doesn't need to use the same backend as the ``default`` + database (although it can use the same backend if you want to). + +If you're using the SQLite database backend, you need to define +:setting:`ENGINE` for both databases, plus a +:setting:`TEST_NAME` for the ``other`` database. The +following is a minimal settings file that can be used to test SQLite:: + + DATABASES = { + 'default': { + 'ENGINE': 'django.db.backends.sqlite3' + }, + 'other': { + 'ENGINE': 'django.db.backends.sqlite3', + 'TEST_NAME': 'other_db' + } + } + +As a convenience, this settings file is included in your Django +distribution. It is called ``test_sqlite``, and is included in +the ``tests`` directory. This allows you to get started running +the tests against the sqlite database without doing anything on +your filesystem. However it should be noted that running against +other database backends is recommended for certain types of test +cases. + +To run the tests with this included settings file, ``cd`` +to the ``tests/`` directory and type: + +.. code-block:: bash + + ./runtests.py --settings=test_sqlite + +If you're using another backend, you will need to provide other details for +each database: + + * The :setting:`USER` option for each of your databases needs to + specify an existing user account for the database. + + * The :setting:`PASSWORD` option needs to provide the password for + the :setting:`USER` that has been specified. + + * The :setting:`NAME` option must be the name of an existing database to + which the given user has permission to connect. The unit tests will not + touch this database; the test runner creates a new database whose name is + :setting:`NAME` prefixed with ``test_``, and this test database is + deleted when the tests are finished. This means your user account needs + permission to execute ``CREATE DATABASE``. + +You will also need to ensure that your database uses UTF-8 as the default +character set. If your database server doesn't use UTF-8 as a default charset, +you will need to include a value for ``TEST_CHARSET`` in the settings +dictionary for the applicable database. + +If you want to run the full suite of tests, you'll need to install a number of +dependencies: + + * PyYAML_ + * Markdown_ + * Textile_ + * Docutils_ + * setuptools_ + * memcached_, plus the either the python-memcached_ or cmemcached_ + Python binding + * gettext_ (:ref:`gettext_on_windows`) + +If you want to test the memcached cache backend, you will also need to define +a :setting:`CACHE_BACKEND` setting that points at your memcached instance. + +Each of these dependencies is optional. If you're missing any of them, the +associated tests will be skipped. + +.. _PyYAML: http://pyyaml.org/wiki/PyYAML +.. _Markdown: http://pypi.python.org/pypi/Markdown/1.7 +.. _Textile: http://pypi.python.org/pypi/textile +.. _docutils: http://pypi.python.org/pypi/docutils/0.4 +.. _setuptools: http://pypi.python.org/pypi/setuptools/ +.. _memcached: http://www.danga.com/memcached/ +.. _python-memcached: http://pypi.python.org/pypi/python-memcached/ +.. _cmemcached: http://gijsbert.org/cmemcache/index.html +.. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html + +To run a subset of the unit tests, append the names of the test modules to the +``runtests.py`` command line. See the list of directories in +``tests/modeltests`` and ``tests/regressiontests`` for module names. + +As an example, if Django is not in your ``PYTHONPATH``, you placed +``settings.py`` in the ``tests/`` directory, and you'd like to only run tests +for generic relations and internationalization, type: + +.. code-block:: bash + + PYTHONPATH=`pwd`/.. + ./runtests.py --settings=settings generic_relations i18n + +Contrib apps +------------ + +Tests for apps in ``django/contrib/`` go in their respective directories under +``django/contrib/``, in a ``tests.py`` file. (You can split the tests over +multiple modules by using a ``tests`` directory in the normal Python way.) + +For the tests to be found, a ``models.py`` file must exist (it doesn't +have to have anything in it). If you have URLs that need to be +mapped, put them in ``tests/urls.py``. + +To run tests for just one contrib app (e.g. ``markup``), use the same +method as above:: + + ./runtests.py --settings=settings markup + +Requesting features +=================== + +We're always trying to make Django better, and your feature requests are a key +part of that. Here are some tips on how to most effectively make a request: + + * Request the feature on `django-developers`_, not in the ticket tracker; + it'll get read more closely if it's on the mailing list. + + * Describe clearly and concisely what the missing feature is and how you'd + like to see it implemented. Include example code (non-functional is OK) + if possible. + + * Explain *why* you'd like the feature. In some cases this is obvious, but + since Django is designed to help real developers get real work done, + you'll need to explain it, if it isn't obvious why the feature would be + useful. + +As with most open-source projects, code talks. If you are willing to write the +code for the feature yourself or if (even better) you've already written it, +it's much more likely to be accepted. If it's a large feature that might need +multiple developers we're always happy to give you an experimental branch in +our repository; see below. + +Branch policy +============= + +In general, the trunk must be kept stable. People should be able to run +production sites against the trunk at any time. Additionally, commits to trunk +ought to be as atomic as possible -- smaller changes are better. Thus, large +feature changes -- that is, changes too large to be encapsulated in a single +patch, or changes that need multiple eyes on them -- must happen on dedicated +branches. + +This means that if you want to work on a large feature -- anything that would +take more than a single patch, or requires large-scale refactoring -- you need +to do it on a feature branch. Our development process recognizes two options +for feature branches: + + 1. Feature branches using a distributed revision control system like + Git_, Mercurial_, Bazaar_, etc. + + If you're familiar with one of these tools, this is probably your best + option since it doesn't require any support or buy-in from the Django + core developers. + + However, do keep in mind that Django will continue to use Subversion for + the foreseeable future, and this will naturally limit the recognition of + your branch. Further, if your branch becomes eligible for merging to + trunk you'll need to find a core developer familiar with your DVCS of + choice who'll actually perform the merge. + + If you do decided to start a distributed branch of Django and choose to make it + public, please add the branch to the `Django branches`_ wiki page. + + 2. Feature branches using SVN have a higher bar. If you want a branch in SVN + itself, you'll need a "mentor" among the :doc:`core committers + </internals/committers>`. This person is responsible for actually creating + the branch, monitoring your process (see below), and ultimately merging + the branch into trunk. + + If you want a feature branch in SVN, you'll need to ask in + `django-developers`_ for a mentor. + +.. _git: http://git-scm.com/ +.. _mercurial: http://mercurial.selenic.com/ +.. _bazaar: http://bazaar.canonical.com/ +.. _django branches: http://code.djangoproject.com/wiki/DjangoBranches + +Branch rules +------------ + +We've got a few rules for branches born out of experience with what makes a +successful Django branch. + +DVCS branches are obviously not under central control, so we have no way of +enforcing these rules. However, if you're using a DVCS, following these rules +will give you the best chance of having a successful branch (read: merged back to +trunk). + +Developers with branches in SVN, however, **must** follow these rules. The +branch mentor will keep on eye on the branch and **will delete it** if these +rules are broken. + + * Only branch entire copies of the Django tree, even if work is only + happening on part of that tree. This makes it painless to switch to a + branch. + + * Merge changes from trunk no less than once a week, and preferably every + couple-three days. + + In our experience, doing regular trunk merges is often the difference + between a successful branch and one that fizzles and dies. + + If you're working on an SVN branch, you should be using `svnmerge.py`_ + to track merges from trunk. + + * Keep tests passing and documentation up-to-date. As with patches, + we'll only merge a branch that comes with tests and documentation. + +.. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py + +Once the branch is stable and ready to be merged into the trunk, alert +`django-developers`_. + +After a branch has been merged, it should be considered "dead"; write access to +it will be disabled, and old branches will be periodically "trimmed." To keep +our SVN wrangling to a minimum, we won't be merging from a given branch into the +trunk more than once. + +Using branches +-------------- + +To use a branch, you'll need to do two things: + + * Get the branch's code through Subversion. + + * Point your Python ``site-packages`` directory at the branch's version of + the ``django`` package rather than the version you already have + installed. + +Getting the code from Subversion +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To get the latest version of a branch's code, check it out using Subversion: + +.. code-block:: bash + + svn co http://code.djangoproject.com/svn/django/branches/<branch>/ + +...where ``<branch>`` is the branch's name. See the `list of branch names`_. + +Alternatively, you can automatically convert an existing directory of the +Django source code as long as you've checked it out via Subversion. To do the +conversion, execute this command from within your ``django`` directory: + +.. code-block:: bash + + svn switch http://code.djangoproject.com/svn/django/branches/<branch>/ + +The advantage of using ``svn switch`` instead of ``svn co`` is that the +``switch`` command retains any changes you might have made to your local copy +of the code. It attempts to merge those changes into the "switched" code. The +disadvantage is that it may cause conflicts with your local changes if the +"switched" code has altered the same lines of code. + +(Note that if you use ``svn switch``, you don't need to point Python at the new +version, as explained in the next section.) + +.. _list of branch names: http://code.djangoproject.com/browser/django/branches + +Pointing Python at the new Django version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once you've retrieved the branch's code, you'll need to change your Python +``site-packages`` directory so that it points to the branch version of the +``django`` directory. (The ``site-packages`` directory is somewhere such as +``/usr/lib/python2.4/site-packages`` or +``/usr/local/lib/python2.4/site-packages`` or ``C:\Python\site-packages``.) + +The simplest way to do this is by renaming the old ``django`` directory to +``django.OLD`` and moving the trunk version of the code into the directory +and calling it ``django``. + +Alternatively, you can use a symlink called ``django`` that points to the +location of the branch's ``django`` package. If you want to switch back, just +change the symlink to point to the old code. + +A third option is to use a `path file`_ (``<something>.pth``) which should +work on all systems (including Windows, which doesn't have symlinks +available). First, make sure there are no files, directories or symlinks named +``django`` in your ``site-packages`` directory. Then create a text file named +``django.pth`` and save it to your ``site-packages`` directory. That file +should contain a path to your copy of Django on a single line and optional +comments. Here is an example that points to multiple branches. Just uncomment +the line for the branch you want to use ('Trunk' in this example) and make +sure all other lines are commented:: + + # Trunk is a svn checkout of: + # http://code.djangoproject.com/svn/django/trunk/ + # + /path/to/trunk + + # <branch> is a svn checkout of: + # http://code.djangoproject.com/svn/django/branches/<branch>/ + # + #/path/to/<branch> + + # On windows a path may look like this: + # C:/path/to/<branch> + +If you're using Django 0.95 or earlier and installed it using +``python setup.py install``, you'll have a directory called something like +``Django-0.95-py2.4.egg`` instead of ``django``. In this case, edit the file +``setuptools.pth`` and remove the line that references the Django ``.egg`` +file. Then copy the branch's version of the ``django`` directory into +``site-packages``. + +.. _path file: http://docs.python.org/library/site.html + +How we make decisions +===================== + +Whenever possible, we strive for a rough consensus. To that end, we'll often +have informal votes on `django-developers`_ about a feature. In these votes we +follow the voting style invented by Apache and used on Python itself, where +votes are given as +1, +0, -0, or -1. Roughly translated, these votes mean: + + * +1: "I love the idea and I'm strongly committed to it." + + * +0: "Sounds OK to me." + + * -0: "I'm not thrilled, but I won't stand in the way." + + * -1: "I strongly disagree and would be very unhappy to see the idea turn + into reality." + +Although these votes on django-developers are informal, they'll be taken very +seriously. After a suitable voting period, if an obvious consensus arises +we'll follow the votes. + +However, consensus is not always possible. If consensus cannot be reached, or +if the discussion towards a consensus fizzles out without a concrete decision, +we use a more formal process. + +Any core committer (see below) may call for a formal vote using the same +voting mechanism above. A proposition will be considered carried by the core team +if: + + * There are three "+1" votes from members of the core team. + + * There is no "-1" vote from any member of the core team. + + * The BDFLs haven't stepped in and executed their positive or negative + veto. + +When calling for a vote, the caller should specify a deadline by which +votes must be received. One week is generally suggested as the minimum +amount of time. + +Since this process allows any core committer to veto a proposal, any "-1" +votes (or BDFL vetos) should be accompanied by an explanation that explains +what it would take to convert that "-1" into at least a "+0". + +Whenever possible, these formal votes should be announced and held in +public on the `django-developers`_ mailing list. However, overly sensitive +or contentious issues -- including, most notably, votes on new core +committers -- may be held in private. + +Commit access +============= + +Django has two types of committers: + +Core committers + These are people who have a long history of contributions to Django's + codebase, a solid track record of being polite and helpful on the + mailing lists, and a proven desire to dedicate serious time to Django's + development. The bar is high for full commit access. + +Partial committers + These are people who are "domain experts." They have direct check-in access + to the subsystems that fall under their jurisdiction, and they're given a + formal vote in questions that involve their subsystems. This type of access + is likely to be given to someone who contributes a large subframework to + Django and wants to continue to maintain it. + + Partial commit access is granted by the same process as full + committers. However, the bar is set lower; proven expertise in the area + in question is likely to be sufficient. + +Decisions on new committers will follow the process explained above in `how +we make decisions`_. + +To request commit access, please contact an existing committer privately. Public +requests for commit access are potential flame-war starters, and will be ignored. + +.. _community page: http://www.djangoproject.com/community/ +.. _ticket tracker: http://code.djangoproject.com/newticket +.. _django-developers: http://groups.google.com/group/django-developers +.. _search the tracker: http://code.djangoproject.com/search +.. _django-users: http://groups.google.com/group/django-users +.. _`#django`: irc://irc.freenode.net/django +.. _list of tickets with patches: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&has_patch=1&order=priority +.. _pep8.py: http://pypi.python.org/pypi/pep8/ +.. _i18n branch: http://code.djangoproject.com/browser/django/branches/i18n +.. _`tags/releases`: http://code.djangoproject.com/browser/django/tags/releases +.. _`easy-pickings`: http://code.djangoproject.com/query?status=new&status=assigned&status=reopened&keywords=~easy-pickings&order=priority diff --git a/parts/django/docs/internals/deprecation.txt b/parts/django/docs/internals/deprecation.txt new file mode 100644 index 0000000..e045795 --- /dev/null +++ b/parts/django/docs/internals/deprecation.txt @@ -0,0 +1,106 @@ +=========================== +Django Deprecation Timeline +=========================== + +This document outlines when various pieces of Django will be removed, following +their deprecation, as per the :ref:`Django deprecation policy +<internal-release-deprecation-policy>` + + * 1.3 + * ``AdminSite.root()``. This release will remove the old method for + hooking up admin URLs. This has been deprecated since the 1.1 + release. + + * Authentication backends need to define the boolean attributes + ``supports_object_permissions`` and ``supports_anonymous_user``. + The old backend style is deprecated since the 1.2 release. + + * The :mod:`django.contrib.gis.db.backend` module, including the + ``SpatialBackend`` interface, is deprecated since the 1.2 release. + + * 1.4 + * ``CsrfResponseMiddleware``. This has been deprecated since the 1.2 + release, in favour of the template tag method for inserting the CSRF + token. ``CsrfMiddleware``, which combines ``CsrfResponseMiddleware`` + and ``CsrfViewMiddleware``, is also deprecated. + + * The old imports for CSRF functionality (``django.contrib.csrf.*``), + which moved to core in 1.2, will be removed. + + * ``SMTPConnection``. The 1.2 release deprecated the ``SMTPConnection`` + class in favor of a generic E-mail backend API. + + * The many to many SQL generation functions on the database backends + will be removed. + + * The ability to use the ``DATABASE_*`` family of top-level settings to + define database connections will be removed. + + * The ability to use shorthand notation to specify a database backend + (i.e., ``sqlite3`` instead of ``django.db.backends.sqlite3``) will be + removed. + + * The ``get_db_prep_save``, ``get_db_prep_value`` and + ``get_db_prep_lookup`` methods on Field were modified in 1.2 to support + multiple databases. In 1.4, the support functions that allow methods + with the old prototype to continue working will be removed. + + * The ``Message`` model (in ``django.contrib.auth``), its related + manager in the ``User`` model (``user.message_set``), and the + associated methods (``user.message_set.create()`` and + ``user.get_and_delete_messages()``), which have + been deprecated since the 1.2 release, will be removed. The + :doc:`messages framework </ref/contrib/messages>` should be used + instead. + + * Authentication backends need to support the ``obj`` parameter for + permission checking. The ``supports_object_permissions`` variable + is not checked any longer and can be removed. + + * Authentication backends need to support the ``AnonymousUser`` + being passed to all methods dealing with permissions. + The ``supports_anonymous_user`` variable is not checked any + longer and can be removed. + + * The ability to specify a callable template loader rather than a + ``Loader`` class will be removed, as will the ``load_template_source`` + functions that are included with the built in template loaders for + backwards compatibility. These have been deprecated since the 1.2 + release. + + * ``django.utils.translation.get_date_formats()`` and + ``django.utils.translation.get_partial_date_formats()``. These + functions are replaced by the new locale aware formatting; use + ``django.utils.formats.get_format()`` to get the appropriate + formats. + + * In ``django.forms.fields``: ``DEFAULT_DATE_INPUT_FORMATS``, + ``DEFAULT_TIME_INPUT_FORMATS`` and + ``DEFAULT_DATETIME_INPUT_FORMATS``. Use + ``django.utils.formats.get_format()`` to get the appropriate + formats. + + * The ability to use a function-based test runners will be removed, + along with the ``django.test.simple.run_tests()`` test runner. + + * The ``views.feed()`` view and ``feeds.Feed`` class in + ``django.contrib.syndication`` have been deprecated since the 1.2 + release. The class-based view ``views.Feed`` should be used instead. + + * ``django.core.context_processors.auth``. This release will + remove the old method in favor of the new method in + ``django.contrib.auth.context_processors.auth``. This has been + deprecated since the 1.2 release. + + * The ``postgresql`` database backend has been deprecated in favor of + the ``postgresql_psycopg2`` backend. + + * The ``no`` language code has been deprecated in favor of the ``nb`` + language code. + + * 2.0 + * ``django.views.defaults.shortcut()``. This function has been moved + to ``django.contrib.contenttypes.views.shortcut()`` as part of the + goal of removing all ``django.contrib`` references from the core + Django codebase. The old shortcut will be removed in the 2.0 + release. diff --git a/parts/django/docs/internals/documentation.txt b/parts/django/docs/internals/documentation.txt new file mode 100644 index 0000000..36270ea --- /dev/null +++ b/parts/django/docs/internals/documentation.txt @@ -0,0 +1,221 @@ +How the Django documentation works +================================== + +\... and how to contribute. + +Django's documentation uses the Sphinx__ documentation system, which in turn is +based on docutils__. The basic idea is that lightly-formatted plain-text +documentation is transformed into HTML, PDF, and any other output format. + +__ http://sphinx.pocoo.org/ +__ http://docutils.sourceforge.net/ + +To actually build the documentation locally, you'll currently need to install +Sphinx -- ``easy_install Sphinx`` should do the trick. + +.. note:: + + The Django documentation can be generated with Sphinx version 0.6 or + newer, but we recommend using Sphinx 1.0.2 or newer. + +Then, building the HTML is easy; just ``make html`` from the ``docs`` directory. + +To get started contributing, you'll want to read the `reStructuredText +Primer`__. After that, you'll want to read about the `Sphinx-specific markup`__ +that's used to manage metadata, indexing, and cross-references. + +__ http://sphinx.pocoo.org/rest.html +__ http://sphinx.pocoo.org/markup/ + +The main thing to keep in mind as you write and edit docs is that the more +semantic markup you can add the better. So:: + + Add ``django.contrib.auth`` to your ``INSTALLED_APPS``... + +Isn't nearly as helpful as:: + + Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`... + +This is because Sphinx will generate proper links for the latter, which greatly +helps readers. There's basically no limit to the amount of useful markup you can +add. + +Django-specific markup +---------------------- + +Besides the `Sphinx built-in markup`__, Django's docs defines some extra description units: + +__ http://sphinx.pocoo.org/markup/desc.html + + * Settings:: + + .. setting:: INSTALLED_APPS + + To link to a setting, use ``:setting:`INSTALLED_APPS```. + + * Template tags:: + + .. templatetag:: regroup + + To link, use ``:ttag:`regroup```. + + * Template filters:: + + .. templatefilter:: linebreaksbr + + To link, use ``:tfilter:`linebreaksbr```. + + * Field lookups (i.e. ``Foo.objects.filter(bar__exact=whatever)``):: + + .. fieldlookup:: exact + + To link, use ``:lookup:`exact```. + + * ``django-admin`` commands:: + + .. django-admin:: syncdb + + To link, use ``:djadmin:`syncdb```. + + * ``django-admin`` command-line options:: + + .. django-admin-option:: --traceback + + To link, use ``:djadminopt:`--traceback```. + +An example +---------- + +For a quick example of how it all fits together, consider this hypothetical +example: + + * First, the ``ref/settings.txt`` document could have an overall layout + like this: + + .. code-block:: rst + + ======== + Settings + ======== + + ... + + .. _available-settings: + + Available settings + ================== + + ... + + .. _deprecated-settings: + + Deprecated settings + =================== + + ... + + * Next, the ``topics/settings.txt`` document could contain something like + this: + + .. code-block:: rst + + You can access a :ref:`listing of all available settings + <available-settings>`. For a list of deprecated settings see + :ref:`deprecated-settings`. + + You can find both in the :doc:`settings reference document </ref/settings>`. + + We use the Sphinx doc_ cross reference element when we want to link to + another document as a whole and the ref_ element when we want to link to + an arbitrary location in a document. + +.. _doc: http://sphinx.pocoo.org/markup/inline.html#role-doc +.. _ref: http://sphinx.pocoo.org/markup/inline.html#role-ref + + * Next, notice how the settings are annotated: + + .. code-block:: rst + + .. setting:: ADMIN_FOR + + ADMIN_FOR + --------- + + Default: ``()`` (Empty tuple) + + Used for admin-site settings modules, this should be a tuple of settings + modules (in the format ``'foo.bar.baz'``) for which this site is an + admin. + + The admin site uses this in its automatically-introspected + documentation of models, views and template tags. + + This marks up the following header as the "canonical" target for the + setting ``ADMIN_FOR`` This means any time I talk about ``ADMIN_FOR``, I + can reference it using ``:setting:`ADMIN_FOR```. + +That's basically how everything fits together. + +TODO +---- + +The work is mostly done, but here's what's left, in rough order of priority. + + * Most of the various ``index.txt`` documents have *very* short or even + non-existent intro text. Each of those documents needs a good short intro + the content below that point. + + * The glossary is very perfunctory. It needs to be filled out. + + * Add more metadata targets: there's lots of places that look like:: + + ``File.close()`` + ~~~~~~~~~~~~~~~~ + + \... these should be:: + + .. method:: File.close() + + That is, use metadata instead of titles. + + * Add more links -- nearly everything that's an inline code literal + right now can probably be turned into a xref. + + See the ``literals_to_xrefs.py`` file in ``_ext`` -- it's a shell script + to help do this work. + + This will probably be a continuing, never-ending project. + + * Add `info field lists`__ where appropriate. + + __ http://sphinx.pocoo.org/markup/desc.html#info-field-lists + + * Add ``.. code-block:: <lang>`` to literal blocks so that they get + highlighted. + +Hints +----- + +Some hints for making things look/read better: + + * Whenever possible, use links. So, use ``:setting:`ADMIN_FOR``` instead of + ````ADMIN_FOR````. + + * Some directives (``.. setting::``, for one) are prefix-style directives; + they go *before* the unit they're describing. These are known as + "crossref" directives. Others (``.. class::``, e.g.) generate their own + markup; these should go inside the section they're describing. These are + called "description units". + + You can tell which are which by looking at in :file:`_ext/djangodocs.py`; + it registers roles as one of the other. + + * When referring to classes/functions/modules, etc., you'll want to use the + fully-qualified name of the target + (``:class:`django.contrib.contenttypes.models.ContentType```). + + Since this doesn't look all that awesome in the output -- it shows the + entire path to the object -- you can prefix the target with a ``~`` + (that's a tilde) to get just the "last bit" of that path. So + ``:class:`~django.contrib.contenttypes.models.ContentType``` will just + display a link with the title "ContentType". diff --git a/parts/django/docs/internals/index.txt b/parts/django/docs/internals/index.txt new file mode 100644 index 0000000..26c941a --- /dev/null +++ b/parts/django/docs/internals/index.txt @@ -0,0 +1,24 @@ +Django internals +================ + +Documentation for people hacking on Django itself. This is the place to go if +you'd like to help improve Django, learn or learn about how Django works "under +the hood". + +.. warning:: + + Elsewhere in the Django documentation, coverage of a feature is a sort of a + contract: once an API is in the official documentation, we consider it + "stable" and don't change it without a good reason. APIs covered here, + however, are considered "internal-only": we reserve the right to change + these internals if we must. + +.. toctree:: + :maxdepth: 1 + + contributing + documentation + committers + release-process + deprecation + svn diff --git a/parts/django/docs/internals/release-process.txt b/parts/django/docs/internals/release-process.txt new file mode 100644 index 0000000..2a56f0b --- /dev/null +++ b/parts/django/docs/internals/release-process.txt @@ -0,0 +1,205 @@ +======================== +Django's release process +======================== + +.. _official-releases: + +Official releases +================= + +Django's release numbering works as follows: + + * Versions are numbered in the form ``A.B`` or ``A.B.C``. + + * ``A`` is the *major version* number, which is only incremented for major + changes to Django, and these changes are not necessarily + backwards-compatible. That is, code you wrote for Django 6.0 may break + when we release Django 7.0. + + * ``B`` is the *minor version* number, which is incremented for large yet + backwards compatible changes. Code written for Django 6.4 will continue + to work under Django 6.5. + + * ``C`` is the *micro version* number which, is incremented for bug and + security fixes. A new micro-release will always be 100% + backwards-compatible with the previous micro-release. + + * In some cases, we'll make alpha, beta, or release candidate releases. + These are of the form ``A.B alpha/beta/rc N``, which means the ``Nth`` + alpha/beta/release candidate of version ``A.B``. + +An exception to this version numbering scheme is the pre-1.0 Django code. +There's no guarantee of backwards-compatibility until the 1.0 release. + +In Subversion, each Django release will be tagged under ``tags/releases``. If +it's necessary to release a bug fix release or a security release that doesn't +come from the trunk, we'll copy that tag to ``branches/releases`` to make the +bug fix release. + +Major releases +-------------- + +Major releases (1.0, 2.0, etc.) will happen very infrequently (think "years", +not "months"), and will probably represent major, sweeping changes to Django. + +Minor releases +-------------- + +Minor release (1.1, 1.2, etc.) will happen roughly every nine months -- see +`release process`_, below for details. + +.. _internal-release-deprecation-policy: + +These releases will contain new features, improvements to existing features, and +such. A minor release may deprecate certain features from previous releases. If a +feature in version ``A.B`` is deprecated, it will continue to work in version +``A.B+1``. In version ``A.B+2``, use of the feature will raise a +``DeprecationWarning`` but will continue to work. Version ``A.B+3`` will +remove the feature entirely. + +So, for example, if we decided to remove a function that existed in Django 1.0: + + * Django 1.1 will contain a backwards-compatible replica of the function + which will raise a ``PendingDeprecationWarning``. This warning is silent + by default; you need to explicitly turn on display of these warnings. + + * Django 1.2 will contain the backwards-compatible replica, but the warning + will be promoted to a full-fledged ``DeprecationWarning``. This warning is + *loud* by default, and will likely be quite annoying. + + * Django 1.3 will remove the feature outright. + +Micro releases +-------------- + +Micro releases (1.0.1, 1.0.2, 1.1.1, etc.) will be issued at least once half-way +between minor releases, and probably more often as needed. + +These releases will always be 100% compatible with the associated minor release +-- the answer to "should I upgrade to the latest micro release?" will always be +"yes." + +Each minor release of Django will have a "release maintainer" appointed. This +person will be responsible for making sure that bug fixes are applied to both +trunk and the maintained micro-release branch. This person will also work with +the release manager to decide when to release the micro releases. + +Supported versions +================== + +At any moment in time, Django's developer team will support a set of releases to +varying levels: + + * The current development trunk will get new features and bug fixes + requiring major refactoring. + + * All bug fixes applied to the trunk will also be applied to the last + minor release, to be released as the next micro release. + + * Security fixes will be applied to the current trunk and the previous two + minor releases. + +As a concrete example, consider a moment in time halfway between the release of +Django 1.3 and 1.4. At this point in time: + + * Features will be added to development trunk, to be released as Django 1.4. + + * Bug fixes will be applied to a ``1.3.X`` branch, and released as 1.3.1, + 1.3.2, etc. + + * Security releases will be applied to trunk, a ``1.3.X`` branch and a + ``1.2.X`` branch. Security fixes will trigger the release of ``1.3.1``, + ``1.2.1``, etc. + +.. _release-process: + +Release process +=============== + +Django uses a time-based release schedule, with minor (i.e. 1.1, 1.2, etc.) +releases every nine months, or more, depending on features. + +After each previous release (and after a suitable cooling-off period of a week +or two), the core development team will examine the landscape and announce a +timeline for the next release. Most releases will be scheduled in the 6-9 month +range, but if we have bigger features to development we might schedule a longer +period to allow for more ambitious work. + +Release cycle +------------- + +Each release cycle will be split into three periods, each lasting roughly +one-third of the cycle: + +Phase one: feature proposal +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The first phase of the release process will be devoted to figuring out what +features to include in the next version. This should include a good deal of +preliminary work on those features -- working code trumps grand design. + +At the end of part one, the core developers will propose a feature list for the +upcoming release. This will be broken into: + +* "Must-have": critical features that will delay the release if not finished +* "Maybe" features: that will be pushed to the next release if not finished +* "Not going to happen": features explicitly deferred to a later release. + +Anything that hasn't got at least some work done by the end of the first third +isn't eligible for the next release; a design alone isn't sufficient. + +Phase two: development +~~~~~~~~~~~~~~~~~~~~~~ + +The second third of the release schedule is the "heads-down" working period. +Using the roadmap produced at the end of phase one, we'll all work very hard to +get everything on it done. + +Longer release schedules will likely spend more than a third of the time in this +phase. + +At the end of phase two, any unfinished "maybe" features will be postponed until +the next release. Though it shouldn't happen, any "must-have" features will +extend phase two, and thus postpone the final release. + +Phase two will culminate with an alpha release. + +Phase three: bugfixes +~~~~~~~~~~~~~~~~~~~~~ + +The last third of a release is spent fixing bugs -- no new features will be +accepted during this time. We'll release a beta release about halfway through, +and an rc complete with string freeze two weeks before the end of the schedule. + +Bug-fix releases +---------------- + +After a minor release (i.e 1.1), the previous release will go into bug-fix mode. + +A branch will be created of the form ``branches/releases/1.0.X`` to track +bug-fixes to the previous release. When possible, bugs fixed on trunk must +*also* be fixed on the bug-fix branch; this means that commits need to cleanly +separate bug fixes from feature additions. The developer who commits a fix to +trunk will be responsible for also applying the fix to the current bug-fix +branch. Each bug-fix branch will have a maintainer who will work with the +committers to keep them honest on backporting bug fixes. + +How this all fits together +-------------------------- + +Let's look at a hypothetical example for how this all first together. Imagine, +if you will, a point about halfway between 1.1 and 1.2. At this point, +development will be happening in a bunch of places: + + * On trunk, development towards 1.2 proceeds with small additions, bugs + fixes, etc. being checked in daily. + + * On the branch "branches/releases/1.1.X", bug fixes found in the 1.1 + release are checked in as needed. At some point, this branch will be + released as "1.1.1", "1.1.2", etc. + + * On the branch "branches/releases/1.0.X", security fixes are made if + needed and released as "1.0.2", "1.0.3", etc. + + * On feature branches, development of major features is done. These + branches will be merged into trunk before the end of phase two. diff --git a/parts/django/docs/internals/svn.txt b/parts/django/docs/internals/svn.txt new file mode 100644 index 0000000..9efbe28 --- /dev/null +++ b/parts/django/docs/internals/svn.txt @@ -0,0 +1,254 @@ +================================= +The Django source code repository +================================= + + +When deploying a Django application into a real production +environment, you will almost always want to use `an official packaged +release of Django`_. However, if you'd like to try out in-development +code from an upcoming release or contribute to the development of +Django, you'll need to obtain a checkout from Django's source code +repository. This document covers the way the code repository is laid +out and how to work with and find things in it. + + +.. _an official packaged release of Django: http://www.djangoproject.com/download/ + + +High-level overview +=================== + +The Django source code repository uses `Subversion`_ to track changes +to the code over time, so you'll need a copy of the Subversion client +(a program called ``svn``) on your computer, and you'll want to +familiarize yourself with the basics of how Subversion +works. Subversion's Web site offers downloads for various operating +systems, and `a free online book`_ is available to help you get up to +speed with using Subversion. + +The Django Subversion repository is located online at +`code.djangoproject.com/svn <http://code.djangoproject.com/svn/>`_. `A +friendly Web-based interface for browsing the code`_ is also +available, though when using Subversion you'll always want to use the +repository address instead. At the top level of the repository are two +directories: ``django`` contains the full source code for all Django +releases, while ``djangoproject.com`` contains the source code and +templates for the `djangoproject.com <http://www.djangoproject.com/>`_ +Web site. For trying out in-development Django code, or contributing +to Django, you'll always want to check out code from some location in +the ``django`` directory. + +Inside the ``django`` directory, Django's source code is organized +into three areas: + +* ``branches`` contains branched copies of Django's code, which are + (or were) maintained for various purposes. Some branches exist to + provide a place to develop major or experimental new features + without affecting the rest of Django's code, while others serve to + provide bug fixes or support for older Django releases. + +* ``tags`` contains snapshots of Django's code at various important + points in its history; mostly these are the exact revisions from + which packaged Django releases were produced. + +* ``trunk`` contains the main in-development code which will become + the next packaged release of Django, and is where most development + activity is focused. + + +.. _Subversion: http://subversion.tigris.org/ +.. _a free online book: http://svnbook.red-bean.com/ +.. _A friendly Web-based interface for browsing the code: http://code.djangoproject.com/browser/ + + +Working with Django's trunk +=========================== + +If you'd like to try out the in-development code for the next release +of Django, or if you'd like to contribute to Django by fixing bugs or +developing new features, you'll want to get the code from trunk. You +can get a complete copy of this code (a "Subversion checkout") by +typing:: + + svn co http://code.djangoproject.com/svn/django/trunk/ + +Note that this will get *all* of Django: in addition to the top-level +``django`` module containing Python code, you'll also get a copy of +Django's documentation, unit-test suite, packaging scripts and other +miscellaneous bits. Django's code will be present in your checkout as +a directory named ``django``. + +To try out the in-development trunk code with your own applications, +simply place the directory containing your checkout on your Python +import path. Then ``import`` statements which look for Django will find +the ``django`` module within your checkout. + +If you're going to be working on Django's code (say, to fix a bug or +develop a new feature), you can probably stop reading here and move +over to :doc:`the documentation for contributing to Django +</internals/contributing>`, which covers things like the preferred +coding style and how to generate and submit a patch. + + +Branches +======== + +Django uses branches for two main purposes: + +1. Development of major or experimental features, to keep them from + affecting progress on other work in trunk. + +2. Security and bug-fix support for older releases of Django, during + their support lifetimes. + + +Feature-development branches +---------------------------- + +Feature-development branches tend by their nature to be +temporary. Some produce successful features which are merged back into +Django's trunk to become part of an official release, but others do +not; in either case there comes a time when the branch is no longer +being actively worked on by any developer. At this point the branch is +considered closed. + +Unfortunately, Subversion has no standard way of indicating this. As a +workaround, branches of Django which are closed and no longer +maintained are moved into the directory ``django/branches/attic``. + +For reference, the following are branches whose code eventually became +part of Django itself, and so are no longer separately maintained: + +* ``boulder-oracle-sprint``: Added support for Oracle databases to + Django's object-relational mapper. This has been part of Django + since the 1.0 release. + +* ``gis``: Added support for geographic/spatial queries to Django's + object-relational mapper. This has been part of Django since the 1.0 + release, as the bundled application ``django.contrib.gis``. + +* ``i18n``: Added :doc:`internationalization support </topics/i18n/index>` to + Django. This has been part of Django since the 0.90 release. + +* ``magic-removal``: A major refactoring of both the internals and + public APIs of Django's object-relational mapper. This has been part + of Django since the 0.95 release. + +* ``multi-auth``: A refactoring of :doc:`Django's bundled + authentication framework </topics/auth>` which added support for + :ref:`authentication backends <authentication-backends>`. This has + been part of Django since the 0.95 release. + +* ``new-admin``: A refactoring of :doc:`Django's bundled + administrative application </ref/contrib/admin/index>`. This became part of + Django as of the 0.91 release, but was superseded by another + refactoring (see next listing) prior to the Django 1.0 release. + +* ``newforms-admin``: The second refactoring of Django's bundled + administrative application. This became part of Django as of the 1.0 + release, and is the basis of the current incarnation of + ``django.contrib.admin``. + +* ``queryset-refactor``: A refactoring of the internals of Django's + object-relational mapper. This became part of Django as of the 1.0 + release. + +* ``unicode``: A refactoring of Django's internals to consistently use + Unicode-based strings in most places within Django and Django + applications. This became part of Django as of the 1.0 release. + +Additionally, the following branches are closed, but their code was +never merged into Django and the features they aimed to implement +were never finished: + +* ``full-history`` + +* ``generic-auth`` + +* ``multiple-db-support`` + +* ``per-object-permissions`` + +* ``schema-evolution`` + +* ``schema-evolution-ng`` + +* ``search-api`` + +* ``sqlalchemy`` + +All of the above-mentioned branches now reside in +``django/branches/attic``. + + +Support and bugfix branches +--------------------------- + +In addition to fixing bugs in current trunk, the Django project +provides official bug-fix support for the most recent released version +of Django, and security support for the two most recently-released +versions of Django. This support is provided via branches in which the +necessary bug or security fixes are applied; the branches are then +used as the basis for issuing bugfix or security releases. + +As of the Django 1.0 release, these branches can be found in the +repository in the directory ``django/branches/releases``, and new branches +will be created there approximately one month after each new Django +release. For example, shortly after the release of Django 1.0, the +branch ``django/branches/releases/1.0.X`` was created to receive bug +fixes, and shortly after the release of Django 1.1 the branch +``django/branches/releases/1.1.X`` was created. + +Prior to the Django 1.0 release, these branches were maintaind within +the top-level ``django/branches`` directory, and so the following +branches exist there and provided support for older Django releases: + +* ``0.90-bugfixes`` + +* ``0.91-bugfixes`` + +* ``0.95-bugfixes`` + +* ``0.96-bugfixes`` + +Official support for those releases has expired, and so they no longer +receive direct maintenance from the Django project. However, the +branches continue to exist and interested community members have +occasionally used them to provide unofficial support for old Django +releases. + + +Tags +==== + +The directory ``django/tags`` within the repository contains complete +copies of the Django source code as it existed at various points in +its history. These "tagged" copies of Django are *never* changed or +updated; new tags may be added as needed, but once added they are +considered read-only and serve as useful guides to Django's +development history. + +Within ``django/tags/releases`` are copies of the code which formed each +packaged release of Django, and each tag is named with the version +number of the release to which it corresponds. So, for example, +``django/tags/releases/1.1`` is a complete copy of the code which was +packaged as the Django 1.1 release. + +Within ``django/tags/notable_moments`` are copies of the Django code from +points which do not directly correspond to releases, but which are +nonetheless important historical milestones for Django +development. The current "notable moments" marked there are: + +* ``ipo``: Django's code as it existed at the moment Django was first + publicly announced in 2005. + +* ``pre-magic-removal``: The state of Django's code just before the + merging of the ``magic-removal`` branch (described above), which + significantly updated Django's object-relational mapper. + +* ``pre-newforms-admin``: The state of Django's code just before the + merging of the ``newforms-admin`` branch (see above), which + significantly updated Django's bundled administrative application. + +* Tags corresponding to each of the alpha, beta and release-candidate + packages in the run up to the Django 1.0 release. |
