diff options
Diffstat (limited to 'parts/django/docs/internals')
| -rw-r--r-- | parts/django/docs/internals/_images/djangotickets.png | bin | 52003 -> 0 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, 0 insertions, 2448 deletions
diff --git a/parts/django/docs/internals/_images/djangotickets.png b/parts/django/docs/internals/_images/djangotickets.png Binary files differdeleted file mode 100644 index 34a2a41..0000000 --- a/parts/django/docs/internals/_images/djangotickets.png +++ /dev/null diff --git a/parts/django/docs/internals/committers.txt b/parts/django/docs/internals/committers.txt deleted file mode 100644 index ecda1d5..0000000 --- a/parts/django/docs/internals/committers.txt +++ /dev/null @@ -1,344 +0,0 @@ -================= -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 deleted file mode 100644 index fd0e48b..0000000 --- a/parts/django/docs/internals/contributing.txt +++ /dev/null @@ -1,1294 +0,0 @@ -====================== -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 deleted file mode 100644 index e045795..0000000 --- a/parts/django/docs/internals/deprecation.txt +++ /dev/null @@ -1,106 +0,0 @@ -=========================== -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 deleted file mode 100644 index 36270ea..0000000 --- a/parts/django/docs/internals/documentation.txt +++ /dev/null @@ -1,221 +0,0 @@ -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 deleted file mode 100644 index 26c941a..0000000 --- a/parts/django/docs/internals/index.txt +++ /dev/null @@ -1,24 +0,0 @@ -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 deleted file mode 100644 index 2a56f0b..0000000 --- a/parts/django/docs/internals/release-process.txt +++ /dev/null @@ -1,205 +0,0 @@ -======================== -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 deleted file mode 100644 index 9efbe28..0000000 --- a/parts/django/docs/internals/svn.txt +++ /dev/null @@ -1,254 +0,0 @@ -================================= -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. |
