PageRenderTime 242ms CodeModel.GetById 21ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/internals/contributing.txt

https://code.google.com/p/mango-py/
Plain Text | 1377 lines | 998 code | 379 blank | 0 comment | 0 complexity | 86b9f6ac43d980a4071fd7a295f21223 MD5 | raw file
Possible License(s): BSD-3-Clause

Large files files are truncated, but you can click here to view the full file

  1. ======================
  2. Contributing to Django
  3. ======================
  4. If you think working *with* Django is fun, wait until you start working *on*
  5. it. We're passionate about helping Django users make the jump to contributing
  6. members of the community, so there are many ways you can help Django's
  7. development:
  8. * Blog about Django. We syndicate all the Django blogs we know about on
  9. the `community page`_; contact jacob@jacobian.org if you've got a blog
  10. you'd like to see on that page.
  11. * Report bugs and request features in our `ticket tracker`_. Please read
  12. `Reporting bugs`_, below, for the details on how we like our bug reports
  13. served up.
  14. * Submit patches for new and/or fixed behavior. Please read `Submitting
  15. patches`_, below, for details on how to submit a patch. If you're looking
  16. for an easy way to start contributing to Django have a look at the
  17. `easy-pickings`_ tickets.
  18. * Join the `django-developers`_ mailing list and share your ideas for how
  19. to improve Django. We're always open to suggestions, although we're
  20. likely to be skeptical of large-scale suggestions without some code to
  21. back it up.
  22. * Triage patches that have been submitted by other users. Please read
  23. `Ticket triage`_ below, for details on the triage process.
  24. That's all you need to know if you'd like to join the Django development
  25. community. The rest of this document describes the details of how our community
  26. works and how it handles bugs, mailing lists, and all the other minutiae of
  27. Django development.
  28. .. seealso::
  29. This document contains specific details for contributing to
  30. Django. However, many new contributors find this guide confusing
  31. or intimidating at first. For a simpler introduction
  32. to becoming a contributor please see the :doc:`/howto/contribute` guide.
  33. .. _reporting-bugs:
  34. Reporting bugs
  35. ==============
  36. Well-written bug reports are *incredibly* helpful. However, there's a certain
  37. amount of overhead involved in working with any bug tracking system so your
  38. help in keeping our ticket tracker as useful as possible is appreciated. In
  39. particular:
  40. * **Do** read the :doc:`FAQ </faq/index>` to see if your issue might
  41. be a well-known question.
  42. * **Do** `search the tracker`_ to see if your issue has already been filed.
  43. * **Do** ask on `django-users`_ *first* if you're not sure if what you're
  44. seeing is a bug.
  45. * **Do** write complete, reproducible, specific bug reports. Include as
  46. much information as you possibly can, complete with code snippets, test
  47. cases, etc. This means including a clear, concise description of the
  48. problem, and a clear set of instructions for replicating the problem.
  49. A minimal example that illustrates the bug in a nice small test case
  50. is the best possible bug report.
  51. * **Don't** use the ticket system to ask support questions. Use the
  52. `django-users`_ list, or the `#django`_ IRC channel for that.
  53. * **Don't** use the ticket system to make large-scale feature requests.
  54. We like to discuss any big changes to Django's core on the
  55. `django-developers`_ list before actually working on them.
  56. * **Don't** reopen issues that have been marked "wontfix". This mark
  57. means that the decision has been made that we can't or won't fix
  58. this particular issue. If you're not sure why, please ask
  59. on `django-developers`_.
  60. * **Don't** use the ticket tracker for lengthy discussions, because they're
  61. likely to get lost. If a particular ticket is controversial, please move
  62. discussion to `django-developers`_.
  63. * **Don't** post to django-developers just to announce that you have filed
  64. a bug report. All the tickets are mailed to another list
  65. (`django-updates`_), which is tracked by developers and interested
  66. community members; we see them as they are filed.
  67. .. _django-updates: http://groups.google.com/group/django-updates
  68. .. _reporting-security-issues:
  69. Reporting security issues
  70. =========================
  71. Report security issues to security@djangoproject.com. This is a private list
  72. only open to long-time, highly trusted Django developers, and its archives are
  73. not publicly readable.
  74. In the event of a confirmed vulnerability in Django itself, we will take the
  75. following actions:
  76. * Acknowledge to the reporter that we've received the report and that a
  77. fix is forthcoming. We'll give a rough timeline and ask the reporter
  78. to keep the issue confidential until we announce it.
  79. * Focus on developing a fix as quickly as possible and produce patches
  80. against the current and two previous releases.
  81. * Determine a go-public date for announcing the vulnerability and the fix.
  82. To try to mitigate a possible "arms race" between those applying the
  83. patch and those trying to exploit the hole, we will not announce
  84. security problems immediately.
  85. * Pre-notify third-party distributors of Django ("vendors"). We will send
  86. these vendor notifications through private email which will include
  87. documentation of the vulnerability, links to the relevant patch(es), and a
  88. request to keep the vulnerability confidential until the official
  89. go-public date.
  90. * Publicly announce the vulnerability and the fix on the pre-determined
  91. go-public date. This will probably mean a new release of Django, but
  92. in some cases it may simply be patches against current releases.
  93. Submitting patches
  94. ==================
  95. We're always grateful for patches to Django's code. Indeed, bug reports
  96. with associated patches will get fixed *far* more quickly than those
  97. without patches.
  98. "Claiming" tickets
  99. ------------------
  100. In an open-source project with hundreds of contributors around the world, it's
  101. important to manage communication efficiently so that work doesn't get
  102. duplicated and contributors can be as effective as possible. Hence, our policy
  103. is for contributors to "claim" tickets in order to let other developers know
  104. that a particular bug or feature is being worked on.
  105. If you have identified a contribution you want to make and you're capable of
  106. fixing it (as measured by your coding ability, knowledge of Django internals
  107. and time availability), claim it by following these steps:
  108. * `Create an account`_ to use in our ticket system.
  109. * If a ticket for this issue doesn't exist yet, create one in our
  110. `ticket tracker`_.
  111. * If a ticket for this issue already exists, make sure nobody else has
  112. claimed it. To do this, look at the "Assigned to" section of the ticket.
  113. If it's assigned to "nobody," then it's available to be claimed.
  114. Otherwise, somebody else is working on this ticket, and you either find
  115. another bug/feature to work on, or contact the developer working on the
  116. ticket to offer your help.
  117. * Log into your account, if you haven't already, by clicking "Login" in the
  118. upper right of the ticket page.
  119. * Claim the ticket by clicking the radio button next to "Accept ticket"
  120. near the bottom of the page, then clicking "Submit changes."
  121. If you have an account but have forgotten your password, you can reset it
  122. using the `password reset page`_.
  123. .. _Create an account: http://www.djangoproject.com/accounts/register/
  124. .. _password reset page: http://www.djangoproject.com/accounts/password/reset/
  125. Ticket claimers' responsibility
  126. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  127. Once you've claimed a ticket, you have a responsibility to work on that ticket
  128. in a reasonably timely fashion. If you don't have time to work on it, either
  129. unclaim it or don't claim it in the first place!
  130. If there's no sign of progress on a particular claimed ticket for a week or
  131. two, another developer may ask you to relinquish the ticket claim so that it's
  132. no longer monopolized and somebody else can claim it.
  133. If you've claimed a ticket and it's taking a long time (days or weeks) to code,
  134. keep everybody updated by posting comments on the ticket. If you don't provide
  135. regular updates, and you don't respond to a request for a progress report,
  136. your claim on the ticket may be revoked. As always, more communication is
  137. better than less communication!
  138. Which tickets should be claimed?
  139. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  140. Of course, going through the steps of claiming tickets is overkill in some
  141. cases. In the case of small changes, such as typos in the documentation or
  142. small bugs that will only take a few minutes to fix, you don't need to jump
  143. through the hoops of claiming tickets. Just submit your patch and be done with
  144. it.
  145. Patch style
  146. -----------
  147. * Make sure your code matches our `coding style`_.
  148. * Submit patches in the format returned by the ``svn diff`` command.
  149. An exception is for code changes that are described more clearly in
  150. plain English than in code. Indentation is the most common example; it's
  151. hard to read patches when the only difference in code is that it's
  152. indented.
  153. Patches in ``git diff`` format are also acceptable.
  154. * When creating patches, always run ``svn diff`` from the top-level
  155. ``trunk`` directory -- i.e., the one that contains ``django``, ``docs``,
  156. ``tests``, ``AUTHORS``, etc. This makes it easy for other people to
  157. apply your patches.
  158. * Attach patches to a ticket in the `ticket tracker`_, using the "attach
  159. file" button. Please *don't* put the patch in the ticket description
  160. or comment unless it's a single line patch.
  161. * Name the patch file with a ``.diff`` extension; this will let the ticket
  162. tracker apply correct syntax highlighting, which is quite helpful.
  163. * Check the "Has patch" box on the ticket details. This will make it
  164. obvious that the ticket includes a patch, and it will add the ticket to
  165. the `list of tickets with patches`_.
  166. * The code required to fix a problem or add a feature is an essential part
  167. of a patch, but it is not the only part. A good patch should also include
  168. a regression test to validate the behavior that has been fixed
  169. (and prevent the problem from arising again).
  170. * If the code associated with a patch adds a new feature, or modifies
  171. behavior of an existing feature, the patch should also contain
  172. documentation.
  173. Non-trivial patches
  174. -------------------
  175. A "non-trivial" patch is one that is more than a simple bug fix. It's a patch
  176. that introduces Django functionality and makes some sort of design decision.
  177. If you provide a non-trivial patch, include evidence that alternatives have
  178. been discussed on `django-developers`_. If you're not sure whether your patch
  179. should be considered non-trivial, just ask.
  180. Ticket triage
  181. =============
  182. Unfortunately, not all bug reports in the `ticket tracker`_ provide all
  183. the `required details`_. A number of tickets have patches, but those patches
  184. don't meet all the requirements of a `good patch`_.
  185. One way to help out is to *triage* bugs that have been reported by other
  186. users. The core team--as well as many community members--work on this
  187. regularly, but more help is always appreciated.
  188. Most of the workflow is based around the concept of a ticket's "triage stage".
  189. This stage describes where in its lifetime a given ticket is at any time.
  190. Along with a handful of flags, this field easily tells us what and who each
  191. ticket is waiting on.
  192. Since a picture is worth a thousand words, let's start there:
  193. .. image:: _images/djangotickets.png
  194. :height: 451
  195. :width: 590
  196. :alt: Django's ticket workflow
  197. We've got two roles in this diagram:
  198. * Core developers: people with commit access who are responsible for
  199. making the big decisions, writing large portions of the code and
  200. integrating the contributions of the community.
  201. * Ticket triagers: anyone in the Django community who chooses to
  202. become involved in Django's development process. Our Trac installation
  203. is :ref:`intentionally left open to the public
  204. <the-spirit-of-contributing>`, and anyone can triage tickets.
  205. Django is a community project, and we encourage `triage by the
  206. community`_.
  207. Triage stages
  208. -------------
  209. Second, note the five triage stages:
  210. 1. A ticket starts as **Unreviewed**, meaning that nobody has examined
  211. the ticket.
  212. 2. **Design decision needed** means "this concept requires a design
  213. decision," which should be discussed either in the ticket comments or on
  214. `django-developers`_. The "Design decision needed" step will generally
  215. only be used for feature requests. It can also be used for issues
  216. that *might* be bugs, depending on opinion or interpretation. Obvious
  217. bugs (such as crashes, incorrect query results, or non-compliance with a
  218. standard) skip this step and move straight to "Accepted".
  219. 3. Once a ticket is ruled to be approved for fixing, it's moved into the
  220. **Accepted** stage. This stage is where all the real work gets done.
  221. 4. In some cases, a ticket might get moved to the **Someday/Maybe** state.
  222. This means the ticket is an enhancement request that we might consider
  223. adding to the framework if an excellent patch is submitted. These
  224. tickets are not a high priority.
  225. 5. If a ticket has an associated patch (see below), it will be reviewed
  226. by the community. If the patch is complete, it'll be marked as **Ready
  227. for checkin** so that a core developer knows to review and commit the
  228. patch.
  229. The second part of this workflow involves a set of flags the describe what the
  230. ticket has or needs in order to be "ready for checkin":
  231. "Has patch"
  232. This means the ticket has an associated patch_. These will be
  233. reviewed to see if the patch is "good".
  234. "Needs documentation"
  235. This flag is used for tickets with patches that need associated
  236. documentation. Complete documentation of features is a prerequisite
  237. before we can check them into the codebase.
  238. "Needs tests"
  239. This flags the patch as needing associated unit tests. Again, this is a
  240. required part of a valid patch.
  241. "Patch needs improvement"
  242. This flag means that although the ticket *has* a patch, it's not quite
  243. ready for checkin. This could mean the patch no longer applies
  244. cleanly, there is a flaw in the implementation, or that the code
  245. doesn't meet our standards.
  246. .. seealso::
  247. The :ref:`contributing howto guide <triage-stages-explained>` has a detailed
  248. explanation of each of the triage stages and how the triage process works in
  249. Trac.
  250. .. _ticket-resolutions:
  251. Ticket Resolutions
  252. ------------------
  253. A ticket can be resolved in a number of ways:
  254. "fixed"
  255. Used by the core developers once a patch has been rolled into
  256. Django and the issue is fixed.
  257. "invalid"
  258. Used if the ticket is found to be incorrect. This means that the
  259. issue in the ticket is actually the result of a user error, or
  260. describes a problem with something other than Django, or isn't
  261. a bug report or feature request at all (for example, some new users
  262. submit support queries as tickets).
  263. "wontfix"
  264. Used when a core developer decides that this request is not
  265. appropriate for consideration in Django. This is usually chosen after
  266. discussion in the ``django-developers`` mailing list. Feel free to
  267. start or join in discussions of "wontfix" tickets on the mailing list,
  268. but please do not reopen tickets closed as "wontfix" by core
  269. developers.
  270. "duplicate"
  271. Used when another ticket covers the same issue. By closing duplicate
  272. tickets, we keep all the discussion in one place, which helps everyone.
  273. "worksforme"
  274. Used when the ticket doesn't contain enough detail to replicate
  275. the original bug.
  276. "needsinfo"
  277. Used when the ticket does not contain enough information to replicate
  278. the reported issue but is potentially still valid. The ticket
  279. should be reopened when more information is supplied.
  280. If you believe that the ticket was closed in error -- because you're
  281. still having the issue, or it's popped up somewhere else, or the triagers have
  282. made a mistake -- please reopen the ticket and provide further information.
  283. Please do not reopen tickets that have been marked as "wontfix" by core
  284. developers.
  285. .. seealso::
  286. For more information on what to do when closing a ticket, please see the
  287. :ref:`contributing howto guide <closing-tickets>`.
  288. .. _required details: `Reporting bugs`_
  289. .. _good patch: `Patch style`_
  290. .. _triage by the community: `Triage by the general community`_
  291. .. _patch: `Submitting patches`_
  292. Triage by the general community
  293. -------------------------------
  294. Although the core developers make the big decisions in the ticket triage
  295. process, there's a lot that general community members can do to help the
  296. triage process. In particular, you can help out by:
  297. * Closing "Unreviewed" tickets as "invalid", "worksforme" or "duplicate."
  298. * Promoting "Unreviewed" tickets to "Design decision needed" if a design
  299. decision needs to be made, or "Accepted" in case of obvious bugs.
  300. * Correcting the "Needs tests", "Needs documentation", or "Has patch"
  301. flags for tickets where they are incorrectly set.
  302. * Adding the `easy-pickings`_ keyword to tickets that are small and
  303. relatively straightforward.
  304. * Checking that old tickets are still valid. If a ticket hasn't seen
  305. any activity in a long time, it's possible that the problem has been
  306. fixed but the ticket hasn't yet been closed.
  307. * Contacting the owners of tickets that have been claimed but have not
  308. seen any recent activity. If the owner doesn't respond after a week
  309. or so, remove the owner's claim on the ticket.
  310. * Identifying trends and themes in the tickets. If there a lot of bug
  311. reports about a particular part of Django, it may indicate we should
  312. consider refactoring that part of the code. If a trend is emerging,
  313. you should raise it for discussion (referencing the relevant tickets)
  314. on `django-developers`_.
  315. However, we do ask the following of all general community members working in
  316. the ticket database:
  317. * Please **don't** close tickets as "wontfix." The core developers will
  318. make the final determination of the fate of a ticket, usually after
  319. consultation with the community.
  320. * Please **don't** promote your own tickets to "Ready for checkin". You
  321. may mark other people's tickets which you've reviewed as "Ready for
  322. checkin", but you should get at minimum one other community member to
  323. review a patch that you submit.
  324. * Please **don't** reverse a decision that has been made by a core
  325. developer. If you disagree with a decision that has been made,
  326. please post a message to `django-developers`_.
  327. * If you're unsure if you should be making a change, don't make the change
  328. but instead leave a comment with your concerns on the ticket, or
  329. post a message to `django-developers`_. It's okay to be unsure, but
  330. your input is still valuable.
  331. .. _contributing-translations:
  332. Submitting and maintaining translations
  333. =======================================
  334. Various parts of Django, such as the admin site and validation error messages,
  335. are internationalized. This means they display different text depending on a
  336. user's language setting. For this, Django uses the same internationalization
  337. infrastructure available to Django applications described in the
  338. :doc:`i18n documentation</topics/i18n/index>`.
  339. These translations are contributed by Django users worldwide. If you find an
  340. incorrect translation or want to discuss specific translations, go to the
  341. `translation team`_ page for that language. If you would like to help out
  342. with translating or add a language that isn't yet translated, here's what
  343. to do:
  344. * Join the `Django i18n mailing list`_ and introduce yourself.
  345. * Make sure you read the notes about :ref:`specialties-of-django-i18n`.
  346. * Signup at `Transifex`_ and visit the `Django project page`_.
  347. * On the "`Translation Teams`_" page, choose the language team you want
  348. to work with, **or** -- in case the language team doesn't exist yet --
  349. request a new team by clicking on the "Request a new team" button
  350. and select the appropriate language.
  351. * Then, click the "Join this Team" button to become a member of this team.
  352. Every team has at least one coordinator who is responsible to review
  353. your membership request. You can of course also contact the team
  354. coordinator to clarify procedural problems and handle the actual
  355. translation process.
  356. * Once you are a member of a team choose the translation resource you
  357. want update on the team page. For example the "core" resource refers
  358. to the translation catalogue that contains all non-app translations.
  359. Each of the contrib apps also have a resource (prefixed with "contrib-").
  360. .. note::
  361. For more information about how to use Transifex, see the
  362. `Transifex Help`_
  363. * Optionally, review and update the ``conf/locale/<locale>/formats.py``
  364. file to describe the date, time and numbers formatting particularities
  365. of your locale. These files aren't covered by the use of Transifex and
  366. require a patch against the Django source tree, just as a code change
  367. would:
  368. * Create a diff against the current Subversion trunk.
  369. * Open a ticket in Django's ticket system, set its ``Component`` field
  370. to ``Translations``, and attach the patch to it. See
  371. :ref:`format-localization` for details.
  372. .. _Django i18n mailing list: http://groups.google.com/group/django-i18n/
  373. .. _Transifex: http://www.transifex.net/
  374. .. _Django project page: http://www.transifex.net/projects/p/django/
  375. .. _translation teams: http://www.transifex.net/projects/p/django/teams/
  376. .. _translation team: http://www.transifex.net/projects/p/django/teams/
  377. .. _Transifex Help: http://help.transifex.net/
  378. Submitting javascript patches
  379. =============================
  380. .. versionadded:: 1.2
  381. Django's admin system leverages the jQuery framework to increase the
  382. capabilities of the admin interface. In conjunction, there is an emphasis on
  383. admin javascript performance and minimizing overall admin media file size.
  384. Serving compressed or "minified" versions of javascript files is considered
  385. best practice in this regard.
  386. To that end, patches for javascript files should include both the original
  387. code for future development (e.g. "foo.js"), and a compressed version for
  388. production use (e.g. "foo.min.js"). Any links to the file in the codebase
  389. should point to the compressed version.
  390. To simplify the process of providing optimized javascript code, Django
  391. includes a handy script which should be used to create a "minified" version.
  392. This script is located at ``/contrib/admin/media/js/compress.py``.
  393. Behind the scenes, ``compress.py`` is a front-end for Google's
  394. `Closure Compiler`_ which is written in Java. However, the Closure Compiler
  395. library is not bundled with Django directly, so those wishing to contribute
  396. complete javascript patches will need to download and install the library
  397. independently.
  398. The Closure Compiler library requires Java version 6 or higher (Java 1.6 or
  399. higher on Mac OS X). Note that Mac OS X 10.5 and earlier did not ship with Java
  400. 1.6 by default, so it may be necessary to upgrade your Java installation before
  401. the tool will be functional. Also note that even after upgrading Java, the
  402. default `/usr/bin/java` command may remain linked to the previous Java
  403. binary, so relinking that command may be necessary as well.
  404. Please don't forget to run ``compress.py`` and include the ``diff`` of the
  405. minified scripts when submitting patches for Django's javascript.
  406. .. _Closure Compiler: http://code.google.com/closure/compiler/
  407. Django conventions
  408. ==================
  409. Various Django-specific code issues are detailed in this section.
  410. Use of ``django.conf.settings``
  411. -------------------------------
  412. Modules should not in general use settings stored in ``django.conf.settings``
  413. at the top level (i.e. evaluated when the module is imported). The explanation
  414. for this is as follows:
  415. Manual configuration of settings (i.e. not relying on the
  416. ``DJANGO_SETTINGS_MODULE`` environment variable) is allowed and possible as
  417. follows::
  418. from django.conf import settings
  419. settings.configure({}, SOME_SETTING='foo')
  420. However, if any setting is accessed before the ``settings.configure`` line,
  421. this will not work. (Internally, ``settings`` is a ``LazyObject`` which
  422. configures itself automatically when the settings are accessed if it has not
  423. already been configured).
  424. So, if there is a module containing some code as follows::
  425. from django.conf import settings
  426. from django.core.urlresolvers import get_callable
  427. default_foo_view = get_callable(settings.FOO_VIEW)
  428. ...then importing this module will cause the settings object to be configured.
  429. That means that the ability for third parties to import the module at the top
  430. level is incompatible with the ability to configure the settings object
  431. manually, or makes it very difficult in some circumstances.
  432. Instead of the above code, a level of laziness or indirection must be used,
  433. such as `django.utils.functional.LazyObject``, ``django.utils.functional.lazy``
  434. or ``lambda``.
  435. Coding style
  436. ============
  437. Please follow these coding standards when writing code for inclusion in Django:
  438. * Unless otherwise specified, follow :pep:`8`.
  439. You could use a tool like `pep8.py`_ to check for some problems in this
  440. area, but remember that PEP 8 is only a guide, so respect the style of
  441. the surrounding code as a primary goal.
  442. * Use four spaces for indentation.
  443. * Use underscores, not camelCase, for variable, function and method names
  444. (i.e. ``poll.get_unique_voters()``, not ``poll.getUniqueVoters``).
  445. * Use ``InitialCaps`` for class names (or for factory functions that
  446. return classes).
  447. * Mark all strings for internationalization; see the :doc:`i18n
  448. documentation </topics/i18n/index>` for details.
  449. * In docstrings, use "action words" such as::
  450. def foo():
  451. """
  452. Calculates something and returns the result.
  453. """
  454. pass
  455. Here's an example of what not to do::
  456. def foo():
  457. """
  458. Calculate something and return the result.
  459. """
  460. pass
  461. * Please don't put your name in the code you contribute. Our policy is to
  462. keep contributors' names in the ``AUTHORS`` file distributed with Django
  463. -- not scattered throughout the codebase itself. Feel free to include a
  464. change to the ``AUTHORS`` file in your patch if you make more than a
  465. single trivial change.
  466. Template style
  467. --------------
  468. * In Django template code, put one (and only one) space between the curly
  469. brackets and the tag contents.
  470. Do this:
  471. .. code-block:: html+django
  472. {{ foo }}
  473. Don't do this:
  474. .. code-block:: html+django
  475. {{foo}}
  476. View style
  477. ----------
  478. * In Django views, the first parameter in a view function should be called
  479. ``request``.
  480. Do this::
  481. def my_view(request, foo):
  482. # ...
  483. Don't do this::
  484. def my_view(req, foo):
  485. # ...
  486. Model style
  487. -----------
  488. * Field names should be all lowercase, using underscores instead of
  489. camelCase.
  490. Do this::
  491. class Person(models.Model):
  492. first_name = models.CharField(max_length=20)
  493. last_name = models.CharField(max_length=40)
  494. Don't do this::
  495. class Person(models.Model):
  496. FirstName = models.CharField(max_length=20)
  497. Last_Name = models.CharField(max_length=40)
  498. * The ``class Meta`` should appear *after* the fields are defined, with
  499. a single blank line separating the fields and the class definition.
  500. Do this::
  501. class Person(models.Model):
  502. first_name = models.CharField(max_length=20)
  503. last_name = models.CharField(max_length=40)
  504. class Meta:
  505. verbose_name_plural = 'people'
  506. Don't do this::
  507. class Person(models.Model):
  508. first_name = models.CharField(max_length=20)
  509. last_name = models.CharField(max_length=40)
  510. class Meta:
  511. verbose_name_plural = 'people'
  512. Don't do this, either::
  513. class Person(models.Model):
  514. class Meta:
  515. verbose_name_plural = 'people'
  516. first_name = models.CharField(max_length=20)
  517. last_name = models.CharField(max_length=40)
  518. * The order of model inner classes and standard methods should be as
  519. follows (noting that these are not all required):
  520. * All database fields
  521. * Custom manager attributes
  522. * ``class Meta``
  523. * ``def __unicode__()``
  524. * ``def __str__()``
  525. * ``def save()``
  526. * ``def get_absolute_url()``
  527. * Any custom methods
  528. * If ``choices`` is defined for a given model field, define the choices as
  529. a tuple of tuples, with an all-uppercase name, either near the top of the
  530. model module or just above the model class. Example::
  531. GENDER_CHOICES = (
  532. ('M', 'Male'),
  533. ('F', 'Female'),
  534. )
  535. Documentation style
  536. ===================
  537. We place a high importance on consistency and readability of documentation.
  538. (After all, Django was created in a journalism environment!)
  539. How to document new features
  540. ----------------------------
  541. We treat our documentation like we treat our code: we aim to improve it as
  542. often as possible. This section explains how writers can craft their
  543. documentation changes in the most useful and least error-prone ways.
  544. Documentation changes come in two forms:
  545. * General improvements -- Typo corrections, error fixes and better
  546. explanations through clearer writing and more examples.
  547. * New features -- Documentation of features that have been added to the
  548. framework since the last release.
  549. Our policy is:
  550. **All documentation of new features should be written in a way that clearly
  551. designates the features are only available in the Django development
  552. version. Assume documentation readers are using the latest release, not the
  553. development version.**
  554. Our preferred way for marking new features is by prefacing the features'
  555. documentation with: ".. versionadded:: X.Y", followed by an optional one line
  556. comment and a mandatory blank line.
  557. General improvements, or other changes to the APIs that should be emphasized
  558. should use the ".. versionchanged:: X.Y" directive (with the same format as the
  559. ``versionadded`` mentioned above.
  560. There's a full page of information about the :doc:`Django documentation
  561. system </internals/documentation>` that you should read prior to working on the
  562. documentation.
  563. Guidelines for reST files
  564. -------------------------
  565. These guidelines regulate the format of our reST documentation:
  566. * In section titles, capitalize only initial words and proper nouns.
  567. * Wrap the documentation at 80 characters wide, unless a code example
  568. is significantly less readable when split over two lines, or for another
  569. good reason.
  570. Commonly used terms
  571. -------------------
  572. Here are some style guidelines on commonly used terms throughout the
  573. documentation:
  574. * **Django** -- when referring to the framework, capitalize Django. It is
  575. lowercase only in Python code and in the djangoproject.com logo.
  576. * **e-mail** -- it has a hyphen.
  577. * **MySQL**
  578. * **PostgreSQL**
  579. * **Python** -- when referring to the language, capitalize Python.
  580. * **realize**, **customize**, **initialize**, etc. -- use the American
  581. "ize" suffix, not "ise."
  582. * **SQLite**
  583. * **subclass** -- it's a single word without a hyphen, both as a verb
  584. ("subclass that model") and as a noun ("create a subclass").
  585. * **Web**, **World Wide Web**, **the Web** -- note Web is always
  586. capitalized when referring to the World Wide Web.
  587. * **Web site** -- use two words, with Web capitalized.
  588. Django-specific terminology
  589. ---------------------------
  590. * **model** -- it's not capitalized.
  591. * **template** -- it's not capitalized.
  592. * **URLconf** -- use three capitalized letters, with no space before
  593. "conf."
  594. * **view** -- it's not capitalized.
  595. Committing code
  596. ===============
  597. Please follow these guidelines when committing code to Django's Subversion
  598. repository:
  599. * For any medium-to-big changes, where "medium-to-big" is according to your
  600. judgment, please bring things up on the `django-developers`_ mailing list
  601. before making the change.
  602. If you bring something up on `django-developers`_ and nobody responds,
  603. please don't take that to mean your idea is great and should be
  604. implemented immediately because nobody contested it. Django's lead
  605. developers don't have a lot of time to read mailing-list discussions
  606. immediately, so you may have to wait a couple of days before getting a
  607. response.
  608. * Write detailed commit messages in the past tense, not present tense.
  609. * Good: "Fixed Unicode bug in RSS API."
  610. * Bad: "Fixes Unicode bug in RSS API."
  611. * Bad: "Fixing Unicode bug in RSS API."
  612. * For commits to a branch, prefix the commit message with the branch name.
  613. For example: "magic-removal: Added support for mind reading."
  614. * Limit commits to the most granular change that makes sense. This means,
  615. use frequent small commits rather than infrequent large commits. For
  616. example, if implementing feature X requires a small change to library Y,
  617. first commit the change to library Y, then commit feature X in a separate
  618. commit. This goes a *long way* in helping all core Django developers
  619. follow your changes.
  620. * Separate bug fixes from feature changes.
  621. Bug fixes need to be added to the current bugfix branch (e.g. the
  622. ``1.0.X`` branch) as well as the current trunk.
  623. * If your commit closes a ticket in the Django `ticket tracker`_, begin
  624. your commit message with the text "Fixed #abc", where "abc" is the number
  625. of the ticket your commit fixes. Example: "Fixed #123 -- Added support
  626. for foo". We've rigged Subversion and Trac so that any commit message
  627. in that format will automatically close the referenced ticket and post a
  628. comment to it with the full commit message.
  629. If your commit closes a ticket and is in a branch, use the branch name
  630. first, then the "Fixed #abc." For example:
  631. "magic-removal: Fixed #123 -- Added whizbang feature."
  632. For the curious: We're using a `Trac post-commit hook`_ for this.
  633. .. _Trac post-commit hook: http://trac.edgewall.org/browser/trunk/contrib/trac-post-commit-hook
  634. * If your commit references a ticket in the Django `ticket tracker`_ but
  635. does *not* close the ticket, include the phrase "Refs #abc", where "abc"
  636. is the number of the ticket your commit references. We've rigged
  637. Subversion and Trac so that any commit message in that format will
  638. automatically post a comment to the appropriate ticket.
  639. Reverting commits
  640. -----------------
  641. Nobody's perfect; mistakes will be committed. When a mistaken commit is
  642. discovered, please follow these guidelines:
  643. * Try very hard to ensure that mistakes don't happen. Just because we
  644. have a reversion policy doesn't relax your responsibility to aim for
  645. the highest quality possible. Really: double-check your work before
  646. you commit it in the first place!
  647. * If possible, have the original author revert his/her own commit.
  648. * Don't revert another author's changes without permission from the
  649. original author.
  650. * If the original author can't be reached (within a reasonable amount
  651. of time -- a day or so) and the problem is severe -- crashing bug,
  652. major test failures, etc -- then ask for objections on django-dev
  653. then revert if there are none.
  654. * If the problem is small (a feature commit after feature freeze,
  655. say), wait it out.
  656. * If there's a disagreement between the committer and the
  657. reverter-to-be then try to work it out on the `django-developers`_
  658. mailing list. If an agreement can't be reached then it should
  659. be put to a vote.
  660. * If the commit introduced a confirmed, disclosed security
  661. vulnerability then the commit may be reverted immediately without
  662. permission from anyone.
  663. * The release branch maintainer may back out commits to the release
  664. branch without permission if the commit breaks the release branch.
  665. .. _unit-tests:
  666. Unit tests
  667. ==========
  668. Django comes with a test suite of its own, in the ``tests`` directory of the
  669. Django tarball. It's our policy to make sure all tests pass at all times.
  670. The tests cover:
  671. * Models and the database API (``tests/modeltests/``).
  672. * Everything else in core Django code (``tests/regressiontests``)
  673. * Contrib apps (``django/contrib/<contribapp>/tests``, see below)
  674. We appreciate any and all contributions to the test suite!
  675. The Django tests all use the testing infrastructure that ships with Django for
  676. testing applications. See :doc:`Testing Django applications </topics/testing>`
  677. for an explanation of how to write new tests.
  678. .. _running-unit-tests:
  679. Running the unit tests
  680. ----------------------
  681. Quickstart
  682. ~~~~~~~~~~
  683. Running the tests requires a Django settings module that defines the
  684. databases to use. To make it easy to get started. Django provides a
  685. sample settings module that uses the SQLite database. To run the tests
  686. with this sample ``settings`` module, ``cd`` into the Django
  687. ``tests/`` directory and run:
  688. .. code-block:: bash
  689. ./runtests.py --settings=test_sqlite
  690. If you get an ``ImportError: No module named django.contrib`` error,
  691. you need to add your install of Django to your ``PYTHONPATH``. For
  692. more details on how to do this, read `Pointing Python at the new
  693. Django version`_ below.
  694. Using another ``settings`` module
  695. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  696. The included settings module allows you to run the test suite using
  697. SQLite. If you want to test behavior using a different database (and
  698. if you're proposing patches for Django, it's a good idea to test
  699. across databases), you may need to define your own settings file.
  700. To run the tests with different settings, ``cd`` to the ``tests/`` directory
  701. and type:
  702. .. code-block:: bash
  703. ./runtests.py --settings=path.to.django.settings
  704. The :setting:`DATABASES` setting in this test settings module needs to define
  705. two databases:
  706. * A ``default`` database. This database should use the backend that
  707. you want to use for primary testing
  708. * A database with the alias ``other``. The ``other`` database is
  709. used to establish that queries can be directed to different
  710. databases. As a result, this database can use any backend you
  711. want. It doesn't need to use the same backend as the ``default``
  712. database (although it can use the same backend if you want to).
  713. If you're using a backend that isn't SQLite, you will need to provide other
  714. details for each database:
  715. * The :setting:`USER` option for each of your databases needs to
  716. specify an existing user account for the database.
  717. * The :setting:`PASSWORD` option needs to provide the password for
  718. the :setting:`USER` that has been specified.
  719. * The :setting:`NAME` option must be the name of an existing database to
  720. which the given user has permission to connect. The unit tests will not
  721. touch this database; the test runner creates a new database whose name is
  722. :setting:`NAME` prefixed with ``test_``, and this test database is
  723. deleted when the tests are finished. This means your user account needs
  724. permission to execute ``CREATE DATABASE``.
  725. You will also need to ensure that your database uses UTF-8 as the default
  726. character set. If your database server doesn't use UTF-8 as a default charset,
  727. you will need to include a value for ``TEST_CHARSET`` in the settings
  728. dictionary for the applicable database.
  729. Running only some of the tests
  730. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  731. Django's entire test suite takes a while to run, and running every single test
  732. could be redundant if, say, you just added a test to Django that you want to
  733. run quickly without running everything else. You can run a subset of the unit
  734. tests by appending the names of the test modules to ``runtests.py`` on the
  735. command line.
  736. For example, if you'd like to run tests only for generic relations and
  737. internationalization, type:
  738. .. code-block:: bash
  739. ./runtests.py --settings=path.to.settings generic_relations i18n
  740. How do you find out the names of individual tests? Look in ``tests/modeltests``
  741. and ``tests/regressiontests`` -- each directory name there is the name of a
  742. test.
  743. If you just want to run a particular class of tests, you can specify a list of
  744. paths to individual test classes. For example, to run the ``TranslationTests``
  745. of the ``i18n`` module, type:
  746. .. code-block:: bash
  747. ./runtests.py --settings=path.to.settings i18n.TranslationTests
  748. Going beyond that, you can specify an individual test method like this:
  749. .. code-block:: bash
  750. ./runtests.py --settings=path.to.settings i18n.TranslationTests.test_lazy_objects
  751. Running all the tests
  752. ~~~~~~~~~~~~~~~~~~~~~
  753. If you want to run the full suite of tests, you'll need to install a number of
  754. dependencies:
  755. * PyYAML_
  756. * Markdown_
  757. * Textile_
  758. * Docutils_
  759. * setuptools_
  760. * memcached_, plus a :ref:`supported Python binding <memcached>`
  761. * gettext_ (:ref:`gettext_on_windows`)
  762. If you want to test the memcached cache backend, you'll also need to define
  763. a :setting:`CACHES` setting that points at your memcached instance.
  764. Each of these dependencies is optional. If you're missing any of them, the
  765. associated tests will be skipped.
  766. .. _PyYAML: http://pyyaml.org/wiki/PyYAML
  767. .. _Markdown: http://pypi.python.org/pypi/Markdown/1.7
  768. .. _Textile: http://pypi.python.org/pypi/textile
  769. .. _docutils: http://pypi.python.org/pypi/docutils/0.4
  770. .. _setuptools: http://pypi.python.org/pypi/setuptools/
  771. .. _memcached: http://www.danga.com/memcached/
  772. .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
  773. Contrib apps
  774. ------------
  775. Tests for apps in ``django/contrib/`` go in their respective directories under
  776. ``django/contrib/``, in a ``tests.py`` file. (You can split the tests over
  777. multiple modules by using a ``tests`` directory in the normal Python way.)
  778. For the tests to be found, a ``models.py`` file must exist (it doesn't
  779. have to have anything in it). If you have URLs that need to be
  780. mapped, put them in ``tests/urls.py``.
  781. To run tests for just one contrib app (e.g. ``markup``), use the same
  782. method as above::
  783. ./runtests.py --settings=settings markup
  784. Requesting features
  785. ===================
  786. We're always trying to make Django better, and your feature requests are a key
  787. part of that. Here are some tips on how to make a request most effectively:
  788. * Request the feature on `django-developers`_, not in the ticket tracker.
  789. It'll get read more closely if it's on the mailing list.
  790. * Describe clearly and concisely what the missing feature is and how you'd
  791. like to see it implemented. Include example code (non-functional is OK)
  792. if possible.
  793. * Explain *why* you'd like the feature. In some cases this is obvious, but
  794. since Django is designed to help real developers get real work done,
  795. you'll need to explain it, if it isn't obvious why the feature would be
  796. useful.
  797. As with most open-source projects, code talks. If you are willing to write the
  798. code for the feature yourself or if (even better) you've already written it,
  799. it's much more likely to be accepted. If it's a large feature that might need
  800. multiple developers, we're always happy to give you an experimental branch in
  801. our repository; see below.
  802. Branch policy
  803. =============
  804. In general, the trunk must be kept stable. People should be able to run
  805. production sites against the trunk at any time. Additionally, commits to trunk
  806. ought to be as atomic as possible -- smaller changes are better. Thus, large
  807. feature changes -- that is, changes too large to be encapsulated in a single
  808. patch, or changes that need multiple eyes on them -- must happen on dedicated
  809. branches.
  810. This means that if you want to work on a large feature -- anything that would
  811. take more than a single patch, or requires large-scale refactoring -- you need
  812. to do it on a feature branch. Our development process recognizes two options
  813. for feature branches:
  814. 1. Feature branches using a distributed revision control system like
  815. Git_, Mercurial_, Bazaar_, etc.
  816. If you're familiar with one of these tools, this is probably your best
  817. option since it doesn't require any support or buy-in from the Django
  818. core developers.
  819. However, do keep in mind that Django will continue to use Subversion for
  820. the foreseeable future, and this will naturally limit the recognition of
  821. your branch. Further, if your branch becomes eligible for merging to
  822. trunk you'll need to find a core developer familiar with your DVCS of
  823. choice who'll actually perform the merge.
  824. If you do decided to start a distributed branch of Django and choose to
  825. make it public, please add the branch to the `Django branches`_ wiki
  826. page.
  827. 2. Feature branches using SVN have a higher bar. If you want a branch
  828. in SVN itself, you'll need a "mentor" among the :doc:`core committers
  829. </internals/committers>`. This person is responsible for actually
  830. creating the branch, monitoring your process (see below), and
  831. ultimately merging the branch into trunk.
  832. If you want a feature branch in SVN, you'll need to ask in
  833. `django-developers`_ for a mentor.
  834. .. _git: http://git-scm.com/
  835. .. _mercurial: http://mercurial.selenic.com/
  836. .. _bazaar: http://bazaar.canonical.com/
  837. .. _django branches: http://code.djangoproject.com/wiki/DjangoBranches
  838. Branch rules
  839. ------------
  840. We've got a few rules for branches born out of experience with what makes a
  841. successful Django branch.
  842. DVCS branches are obviously not under central control, so we have no way of
  843. enforcing these rules. However, if you're using a DVCS, following these rules
  844. will give you the best chance of having a successful branch (read: merged back
  845. to trunk).
  846. Developers with branches in SVN, however, **must** follow these rules. The
  847. branch mentor will keep on eye on the branch and **will delete it** if these
  848. rules are broken.
  849. * Only branch entire copies of the Django tree, even if work is only
  850. happening on part of that tree. This makes it painless to switch to a
  851. branch.
  852. * Merge changes from trunk no less than once a week, and preferably every
  853. couple-three days.
  854. In our experience, doing regular trunk merges is often the difference
  855. between a successful branch and one that fizzles and dies.
  856. If you're working on an SVN branch, you should be using `svnmerge.py`_
  857. to track merges from trunk.
  858. * Keep tests passing and documentation up-to-date. As with patches,
  859. we'll only merge a branch that comes with tests and documentation.
  860. .. _svnmerge.py: http://www.orcaware.com/svn/wiki/Svnmerge.py
  861. Once the branch is stable and ready to be merged into the trunk, alert
  862. `django-developers`_.
  863. After a branch has been merged, it should be considered "dead"; write access to
  864. it will be disabled, and old branches will be periodically "trimmed." To keep
  865. our SVN wrangling to a minimum, we won't be merging from a given branch into
  866. the trunk more than once.
  867. Using branches
  868. --------------
  869. To use a branch, you'll need to do two things:
  870. * Get the branch's code through Subversion.
  871. * Point your Python ``site-packages`` directory at the branch's version of
  872. the ``django`` package rather than the version you already have
  873. installed.
  874. Getting the code from Subversion
  875. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  876. To get the latest version of a branch's code, check it out using Subversion:
  877. .. code-block:: bash
  878. svn co http://code.djangoproject.com/svn/django/branches/<branch>/
  879. ...where ``<branch>`` is the branch's name. See the `list of branch names`_.
  880. Alternatively, you can automatically convert an existing directory of the
  881. Django source code as long as you've checked it out via Subversion. To do the
  882. conversion, execute this command from within your ``django`` directory:
  883. .. code-block:: bash
  884. svn switch http://code.djangoproject.com/svn/django/branches/<branch>/
  885. The advantage of using ``svn switch`` instead of ``svn co`` is that the
  886. ``switch`` command retains any changes you might have made to your local copy
  887. of the code. It attempts to merge those changes into the "switched" code. The
  888. disadvantage is that it may cause conflicts with your local changes if the
  889. "switched" code has altered the same lines of code.
  890. (Note that if you use ``svn switch``, you don't need to point Python at the new
  891. version, as explained in the next section.)
  892. .. _list of branch names: http://code.djangoproject.com/browser/django/branches
  893. Pointing Python at the new Django version
  894. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  895. Once you've retrieved the branch's code, you'll need to change your Python
  896. ``site-packages`` directory so that it points to the branch version of the
  897. ``django`` directory. (The ``site-packages`` directory is somewhere such as
  898. ``/usr/lib/python2.4/site-packages`` or
  899. ``/usr/local/lib/python2.4/site-packā€¦

Large files files are truncated, but you can click here to view the full file