From 7fe70e60d0a9e2b91ae292e951239db0c26f8fd0 Mon Sep 17 00:00:00 2001 From: a <455919189@qq.com> Date: Tue, 17 May 2022 21:04:08 +0800 Subject: [PATCH] =?UTF-8?q?=E4=B8=8A=E4=BC=A0=E6=96=87=E4=BB=B6=E8=87=B3?= =?UTF-8?q?=20'test/Django-2.1.15/docs/internals'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../docs/internals/deprecation.txt | 1023 +++++++++++++++++ test/Django-2.1.15/docs/internals/git.txt | 249 ++++ .../docs/internals/howto-release-django.txt | 434 +++++++ test/Django-2.1.15/docs/internals/index.txt | 18 + .../docs/internals/mailing-lists.txt | 126 ++ 5 files changed, 1850 insertions(+) create mode 100644 test/Django-2.1.15/docs/internals/deprecation.txt create mode 100644 test/Django-2.1.15/docs/internals/git.txt create mode 100644 test/Django-2.1.15/docs/internals/howto-release-django.txt create mode 100644 test/Django-2.1.15/docs/internals/index.txt create mode 100644 test/Django-2.1.15/docs/internals/mailing-lists.txt diff --git a/test/Django-2.1.15/docs/internals/deprecation.txt b/test/Django-2.1.15/docs/internals/deprecation.txt new file mode 100644 index 0000000..244b5e3 --- /dev/null +++ b/test/Django-2.1.15/docs/internals/deprecation.txt @@ -0,0 +1,1023 @@ +=========================== +Django Deprecation Timeline +=========================== + +This document outlines when various pieces of Django will be removed or altered +in a backward incompatible way, following their deprecation, as per the +:ref:`deprecation policy `. More details +about each item can often be found in the release notes of two versions prior. + +.. _deprecation-removed-in-3.0: + +3.0 +--- + +See the :ref:`Django 2.0 release notes` for more +details on these changes. + +* The ``django.db.backends.postgresql_psycopg2`` module will be removed. + +* ``django.shortcuts.render_to_response()`` will be removed. + +* The ``DEFAULT_CONTENT_TYPE`` setting will be removed. + +* ``HttpRequest.xreadlines()`` will be removed. + +* Support for the ``context`` argument of ``Field.from_db_value()`` and + ``Expression.convert_value()`` will be removed. + +* The ``field_name`` keyword argument of ``QuerySet.earliest()`` and + ``latest()`` will be removed. + +See the :ref:`Django 2.1 release notes ` for more +details on these changes. + +* ``django.contrib.gis.db.models.functions.ForceRHR`` will be removed. + +* ``django.utils.http.cookie_date()`` will be removed. + +* The ``staticfiles`` and ``admin_static`` template tag libraries will be + removed. + +* ``django.contrib.staticfiles.templatetags.static()`` will be removed. + +* The shim to allow ``InlineModelAdmin.has_add_permission()`` to be defined + without an ``obj`` argument will be removed. + +.. _deprecation-removed-in-2.1: + +2.1 +--- + +See the :ref:`Django 1.11 release notes` for more +details on these changes. + +* ``contrib.auth.views.login()``, ``logout()``, ``password_change()``, + ``password_change_done()``, ``password_reset()``, ``password_reset_done()``, + ``password_reset_confirm()``, and ``password_reset_complete()`` will be + removed. + +* The ``extra_context`` parameter of ``contrib.auth.views.logout_then_login()`` + will be removed. + +* ``django.test.runner.setup_databases()`` will be removed. + +* ``django.utils.translation.string_concat()`` will be removed. + +* ``django.core.cache.backends.memcached.PyLibMCCache`` will no longer support + passing ``pylibmc`` behavior settings as top-level attributes of ``OPTIONS``. + +* The ``host`` parameter of ``django.utils.http.is_safe_url()`` will be + removed. + +* Silencing of exceptions raised while rendering the ``{% include %}`` template + tag will be removed. + +* ``DatabaseIntrospection.get_indexes()`` will be removed. + +* The ``authenticate()`` method of authentication backends will require + ``request`` as the first positional argument. + +* The ``django.db.models.permalink()`` decorator will be removed. + +* The ``USE_ETAGS`` setting will be removed. ``CommonMiddleware`` and + ``django.utils.cache.patch_response_headers()`` will no longer set ETags. + +* The ``Model._meta.has_auto_field`` attribute will be removed. + +* ``url()``'s support for inline flags in regular expression groups (``(?i)``, + ``(?L)``, ``(?m)``, ``(?s)``, and ``(?u)``) will be removed. + +* Support for ``Widget.render()`` methods without the ``renderer`` argument + will be removed. + +.. _deprecation-removed-in-2.0: + +2.0 +--- + +See the :ref:`Django 1.9 release notes` for more +details on these changes. + +* The ``weak`` argument to ``django.dispatch.signals.Signal.disconnect()`` will + be removed. + +* ``django.db.backends.base.BaseDatabaseOperations.check_aggregate_support()`` + will be removed. + +* The ``django.forms.extras`` package will be removed. + +* The ``assignment_tag`` helper will be removed. + +* The ``host`` argument to ``assertsRedirects`` will be removed. The + compatibility layer which allows absolute URLs to be considered equal to + relative ones when the path is identical will also be removed. + +* ``Field.rel`` will be removed. + +* ``Field.remote_field.to`` attribute will be removed. + +* The ``on_delete`` argument for ``ForeignKey`` and ``OneToOneField`` will be + required. + +* ``django.db.models.fields.add_lazy_relation()`` will be removed. + +* When time zone support is enabled, database backends that don't support time + zones won't convert aware datetimes to naive values in UTC anymore when such + values are passed as parameters to SQL queries executed outside of the ORM, + e.g. with ``cursor.execute()``. + +* The ``django.contrib.auth.tests.utils.skipIfCustomUser()`` decorator will be + removed. + +* The ``GeoManager`` and ``GeoQuerySet`` classes will be removed. + +* The ``django.contrib.gis.geoip`` module will be removed. + +* The ``supports_recursion`` check for template loaders will be removed from: + + * ``django.template.engine.Engine.find_template()`` + * ``django.template.loader_tags.ExtendsNode.find_template()`` + * ``django.template.loaders.base.Loader.supports_recursion()`` + * ``django.template.loaders.cached.Loader.supports_recursion()`` + +* The ``load_template()`` and ``load_template_sources()`` template loader + methods will be removed. + +* The ``template_dirs`` argument for template loaders will be removed: + + * ``django.template.loaders.base.Loader.get_template()`` + * ``django.template.loaders.cached.Loader.cache_key()`` + * ``django.template.loaders.cached.Loader.get_template()`` + * ``django.template.loaders.cached.Loader.get_template_sources()`` + * ``django.template.loaders.filesystem.Loader.get_template_sources()`` + +* The ``django.template.loaders.base.Loader.__call__()`` method will be + removed. + +* Support for custom error views with a single positional parameter will be + dropped. + +* The ``mime_type`` attribute of ``django.utils.feedgenerator.Atom1Feed`` and + ``django.utils.feedgenerator.RssFeed`` will be removed in favor of + ``content_type``. + +* The ``app_name`` argument to ``django.conf.urls.include()`` will be + removed. + +* Support for passing a 3-tuple as the first argument to ``include()`` will + be removed. + +* Support for setting a URL instance namespace without an application + namespace will be removed. + +* ``Field._get_val_from_obj()`` will be removed in favor of + ``Field.value_from_object()``. + +* ``django.template.loaders.eggs.Loader`` will be removed. + +* The ``current_app`` parameter to the ``contrib.auth`` views will be removed. + +* The ``callable_obj`` keyword argument to + ``SimpleTestCase.assertRaisesMessage()`` will be removed. + +* Support for the ``allow_tags`` attribute on ``ModelAdmin`` methods will be + removed. + +* The ``enclosure`` keyword argument to ``SyndicationFeed.add_item()`` will be + removed. + +* The ``django.template.loader.LoaderOrigin`` and + ``django.template.base.StringOrigin`` aliases for + ``django.template.base.Origin`` will be removed. + +See the :ref:`Django 1.10 release notes ` for more +details on these changes. + +* The ``makemigrations --exit`` option will be removed. + +* Support for direct assignment to a reverse foreign key or many-to-many + relation will be removed. + +* The ``get_srid()`` and ``set_srid()`` methods of + ``django.contrib.gis.geos.GEOSGeometry`` will be removed. + +* The ``get_x()``, ``set_x()``, ``get_y()``, ``set_y()``, ``get_z()``, and + ``set_z()`` methods of ``django.contrib.gis.geos.Point`` will be removed. + +* The ``get_coords()`` and ``set_coords()`` methods of + ``django.contrib.gis.geos.Point`` will be removed. + +* The ``cascaded_union`` property of ``django.contrib.gis.geos.MultiPolygon`` + will be removed. + +* ``django.utils.functional.allow_lazy()`` will be removed. + +* The ``shell --plain`` option will be removed. + +* The ``django.core.urlresolvers`` module will be removed. + +* The model ``CommaSeparatedIntegerField`` will be removed. A stub field will + remain for compatibility with historical migrations. + +* Support for the template ``Context.has_key()`` method will be removed. + +* Support for the ``django.core.files.storage.Storage.accessed_time()``, + ``created_time()``, and ``modified_time()`` methods will be removed. + +* Support for query lookups using the model name when + ``Meta.default_related_name`` is set will be removed. + +* The ``__search`` query lookup and the + ``DatabaseOperations.fulltext_search_sql()`` method will be removed. + +* The shim for supporting custom related manager classes without a + ``_apply_rel_filters()`` method will be removed. + +* Using ``User.is_authenticated()`` and ``User.is_anonymous()`` as methods + will no longer be supported. + +* The private attribute ``virtual_fields`` of ``Model._meta`` will be removed. + +* The private keyword arguments ``virtual_only`` in + ``Field.contribute_to_class()`` and ``virtual`` in + ``Model._meta.add_field()`` will be removed. + +* The ``javascript_catalog()`` and ``json_catalog()`` views will be removed. + +* The ``django.contrib.gis.utils.precision_wkt()`` function will be removed. + +* In multi-table inheritance, implicit promotion of a ``OneToOneField`` to a + ``parent_link`` will be removed. + +* Support for ``Widget._format_value()`` will be removed. + +* ``FileField`` methods ``get_directory_name()`` and ``get_filename()`` will be + removed. + +* The ``mark_for_escaping()`` function and the classes it uses: ``EscapeData``, + ``EscapeBytes``, ``EscapeText``, ``EscapeString``, and ``EscapeUnicode`` will + be removed. + +* The ``escape`` filter will change to use + ``django.utils.html.conditional_escape()``. + +* ``Manager.use_for_related_fields`` will be removed. + +* Model ``Manager`` inheritance will follow MRO inheritance rules and the + ``Meta.manager_inheritance_from_future`` to opt-in to this behavior will be + removed. + +* Support for old-style middleware using ``settings.MIDDLEWARE_CLASSES`` will + be removed. + +.. _deprecation-removed-in-1.10: + +1.10 +---- + +See the :ref:`Django 1.8 release notes` for more +details on these changes. + +* Support for calling a ``SQLCompiler`` directly as an alias for calling its + ``quote_name_unless_alias`` method will be removed. + +* ``cycle`` and ``firstof`` template tags will be removed from the ``future`` + template tag library (used during the 1.6/1.7 deprecation period). + +* ``django.conf.urls.patterns()`` will be removed. + +* Support for the ``prefix`` argument to + ``django.conf.urls.i18n.i18n_patterns()`` will be removed. + +* ``SimpleTestCase.urls`` will be removed. + +* Using an incorrect count of unpacked values in the ``for`` template tag + will raise an exception rather than fail silently. + +* The ability to reverse URLs using a dotted Python path will be removed. + +* The ability to use a dotted Python path for the ``LOGIN_URL`` and + ``LOGIN_REDIRECT_URL`` settings will be removed. + +* Support for :py:mod:`optparse` will be dropped for custom management commands + (replaced by :py:mod:`argparse`). + +* The class ``django.core.management.NoArgsCommand`` will be removed. Use + :class:`~django.core.management.BaseCommand` instead, which takes no arguments + by default. + +* ``django.core.context_processors`` module will be removed. + +* ``django.db.models.sql.aggregates`` module will be removed. + +* ``django.contrib.gis.db.models.sql.aggregates`` module will be removed. + +* The following methods and properties of ``django.db.sql.query.Query`` will + be removed: + + * Properties: ``aggregates`` and ``aggregate_select`` + * Methods: ``add_aggregate``, ``set_aggregate_mask``, and + ``append_aggregate_mask``. + +* ``django.template.resolve_variable`` will be removed. + +* The following private APIs will be removed from + :class:`django.db.models.options.Options` (``Model._meta``): + + * ``get_field_by_name()`` + * ``get_all_field_names()`` + * ``get_fields_with_model()`` + * ``get_concrete_fields_with_model()`` + * ``get_m2m_with_model()`` + * ``get_all_related_objects()`` + * ``get_all_related_objects_with_model()`` + * ``get_all_related_many_to_many_objects()`` + * ``get_all_related_m2m_objects_with_model()`` + +* The ``error_message`` argument of ``django.forms.RegexField`` will be removed. + +* The ``unordered_list`` filter will no longer support old style lists. + +* Support for string ``view`` arguments to ``url()`` will be removed. + +* The backward compatible shim to rename ``django.forms.Form._has_changed()`` + to ``has_changed()`` will be removed. + +* The ``removetags`` template filter will be removed. + +* The ``remove_tags()`` and ``strip_entities()`` functions in + ``django.utils.html`` will be removed. + +* The ``is_admin_site`` argument to + ``django.contrib.auth.views.password_reset()`` will be removed. + +* ``django.db.models.field.subclassing.SubfieldBase`` will be removed. + +* ``django.utils.checksums`` will be removed; its functionality is included + in ``django-localflavor`` 1.1+. + +* The ``original_content_type_id`` attribute on + ``django.contrib.admin.helpers.InlineAdminForm`` will be removed. + +* The backwards compatibility shim to allow ``FormMixin.get_form()`` to be + defined with no default value for its ``form_class`` argument will be removed. + +* The following settings will be removed: + + * ``ALLOWED_INCLUDE_ROOTS`` + * ``TEMPLATE_CONTEXT_PROCESSORS`` + * ``TEMPLATE_DEBUG`` + * ``TEMPLATE_DIRS`` + * ``TEMPLATE_LOADERS`` + * ``TEMPLATE_STRING_IF_INVALID`` + +* The backwards compatibility alias ``django.template.loader.BaseLoader`` will + be removed. + +* Django template objects returned by + :func:`~django.template.loader.get_template` and + :func:`~django.template.loader.select_template` won't accept a + :class:`~django.template.Context` in their + :meth:`~django.template.backends.base.Template.render()` method anymore. + +* :doc:`Template response APIs ` will enforce the use + of :class:`dict` and backend-dependent template objects instead of + :class:`~django.template.Context` and :class:`~django.template.Template` + respectively. + +* The ``current_app`` parameter for the following function and classes will be + removed: + + * ``django.shortcuts.render()`` + * ``django.template.Context()`` + * ``django.template.RequestContext()`` + * ``django.template.response.TemplateResponse()`` + +* The ``dictionary`` and ``context_instance`` parameters for the following + functions will be removed: + + * ``django.shortcuts.render()`` + * ``django.shortcuts.render_to_response()`` + * ``django.template.loader.render_to_string()`` + +* The ``dirs`` parameter for the following functions will be removed: + + * ``django.template.loader.get_template()`` + * ``django.template.loader.select_template()`` + * ``django.shortcuts.render()`` + * ``django.shortcuts.render_to_response()`` + +* Session verification will be enabled regardless of whether or not + ``'django.contrib.auth.middleware.SessionAuthenticationMiddleware'`` is in + ``MIDDLEWARE_CLASSES``. + +* Private attribute ``django.db.models.Field.related`` will be removed. + +* The ``--list`` option of the ``migrate`` management command will be removed. + +* The ``ssi`` template tag will be removed. + +* Support for the ``=`` comparison operator in the ``if`` template tag will be + removed. + +* The backwards compatibility shims to allow ``Storage.get_available_name()`` + and ``Storage.save()`` to be defined without a ``max_length`` argument will + be removed. + +* Support for the legacy ``%()s`` syntax in ``ModelFormMixin.success_url`` + will be removed. + +* ``GeoQuerySet`` aggregate methods ``collect()``, ``extent()``, ``extent3d()``, + ``make_line()``, and ``unionagg()`` will be removed. + +* Ability to specify ``ContentType.name`` when creating a content type instance + will be removed. + +* Support for the old signature of ``allow_migrate`` will be removed. It changed + from ``allow_migrate(self, db, model)`` to + ``allow_migrate(self, db, app_label, model_name=None, **hints)``. + +* Support for the syntax of ``{% cycle %}`` that uses comma-separated arguments + will be removed. + +* The warning that :class:`~django.core.signing.Signer` issues when given an + invalid separator will become an exception. + +.. _deprecation-removed-in-1.9: + +1.9 +--- + +See the :ref:`Django 1.7 release notes` for more +details on these changes. + +* ``django.utils.dictconfig`` will be removed. + +* ``django.utils.importlib`` will be removed. + +* ``django.utils.tzinfo`` will be removed. + +* ``django.utils.unittest`` will be removed. + +* The ``syncdb`` command will be removed. + +* ``django.db.models.signals.pre_syncdb`` and + ``django.db.models.signals.post_syncdb`` will be removed. + +* ``allow_syncdb`` on database routers will no longer automatically become + ``allow_migrate``. + +* Automatic syncing of apps without migrations will be removed. Migrations will + become compulsory for all apps unless you pass the ``--run-syncdb`` option to + ``migrate``. + +* The SQL management commands for apps without migrations, ``sql``, ``sqlall``, + ``sqlclear``, ``sqldropindexes``, and ``sqlindexes``, will be removed. + +* Support for automatic loading of ``initial_data`` fixtures and initial SQL + data will be removed. + +* All models will need to be defined inside an installed application or + declare an explicit :attr:`~django.db.models.Options.app_label`. + Furthermore, it won't be possible to import them before their application + is loaded. In particular, it won't be possible to import models inside + the root package of their application. + +* The model and form ``IPAddressField`` will be removed. A stub field will + remain for compatibility with historical migrations. + +* ``AppCommand.handle_app()`` will no longer be supported. + +* ``RequestSite`` and ``get_current_site()`` will no longer be importable from + ``django.contrib.sites.models``. + +* FastCGI support via the ``runfcgi`` management command will be + removed. Please deploy your project using WSGI. + +* ``django.utils.datastructures.SortedDict`` will be removed. Use + :class:`collections.OrderedDict` from the Python standard library instead. + +* ``ModelAdmin.declared_fieldsets`` will be removed. + +* Instances of ``util.py`` in the Django codebase have been renamed to + ``utils.py`` in an effort to unify all util and utils references. + The modules that provided backwards compatibility will be removed: + + * ``django.contrib.admin.util`` + * ``django.contrib.gis.db.backends.util`` + * ``django.db.backends.util`` + * ``django.forms.util`` + +* ``ModelAdmin.get_formsets`` will be removed. + +* The backward compatibility shim introduced to rename the + ``BaseMemcachedCache._get_memcache_timeout()`` method to + ``get_backend_timeout()`` will be removed. + +* The ``--natural`` and ``-n`` options for :djadmin:`dumpdata` will be removed. + +* The ``use_natural_keys`` argument for ``serializers.serialize()`` will be + removed. + +* Private API ``django.forms.forms.get_declared_fields()`` will be removed. + +* The ability to use a ``SplitDateTimeWidget`` with ``DateTimeField`` will be + removed. + +* The ``WSGIRequest.REQUEST`` property will be removed. + +* The class ``django.utils.datastructures.MergeDict`` will be removed. + +* The ``zh-cn`` and ``zh-tw`` language codes will be removed and have been + replaced by the ``zh-hans`` and ``zh-hant`` language code respectively. + +* The internal ``django.utils.functional.memoize`` will be removed. + +* ``django.core.cache.get_cache`` will be removed. Add suitable entries + to :setting:`CACHES` and use :data:`django.core.cache.caches` instead. + +* ``django.db.models.loading`` will be removed. + +* Passing callable arguments to querysets will no longer be possible. + +* ``BaseCommand.requires_model_validation`` will be removed in favor of + ``requires_system_checks``. Admin validators will be replaced by admin + checks. + +* The ``ModelAdmin.validator_class`` and ``default_validator_class`` attributes + will be removed. + +* ``ModelAdmin.validate()`` will be removed. + +* ``django.db.backends.DatabaseValidation.validate_field`` will be removed in + favor of the ``check_field`` method. + +* The ``validate`` management command will be removed. + +* ``django.utils.module_loading.import_by_path`` will be removed in favor of + ``django.utils.module_loading.import_string``. + +* ``ssi`` and ``url`` template tags will be removed from the ``future`` template + tag library (used during the 1.3/1.4 deprecation period). + +* ``django.utils.text.javascript_quote`` will be removed. + +* Database test settings as independent entries in the database settings, + prefixed by ``TEST_``, will no longer be supported. + +* The `cache_choices` option to :class:`~django.forms.ModelChoiceField` and + :class:`~django.forms.ModelMultipleChoiceField` will be removed. + +* The default value of the + :attr:`RedirectView.permanent ` + attribute will change from ``True`` to ``False``. + +* ``django.contrib.sitemaps.FlatPageSitemap`` will be removed in favor of + ``django.contrib.flatpages.sitemaps.FlatPageSitemap``. + +* Private API ``django.test.utils.TestTemplateLoader`` will be removed. + +* The ``django.contrib.contenttypes.generic`` module will be removed. + +* Private APIs ``django.db.models.sql.where.WhereNode.make_atom()`` and + ``django.db.models.sql.where.Constraint`` will be removed. + +.. _deprecation-removed-in-1.8: + +1.8 +--- + +See the :ref:`Django 1.6 release notes` for more +details on these changes. + +* ``django.contrib.comments`` will be removed. + +* The following transaction management APIs will be removed: + + - ``TransactionMiddleware``, + - the decorators and context managers ``autocommit``, ``commit_on_success``, + and ``commit_manually``, defined in ``django.db.transaction``, + - the functions ``commit_unless_managed`` and ``rollback_unless_managed``, + also defined in ``django.db.transaction``, + - the ``TRANSACTIONS_MANAGED`` setting. + +* The :ttag:`cycle` and :ttag:`firstof` template tags will auto-escape their + arguments. In 1.6 and 1.7, this behavior is provided by the version of these + tags in the ``future`` template tag library. + +* The ``SEND_BROKEN_LINK_EMAILS`` setting will be removed. Add the + :class:`django.middleware.common.BrokenLinkEmailsMiddleware` middleware to + your ``MIDDLEWARE_CLASSES`` setting instead. + +* ``django.middleware.doc.XViewMiddleware`` will be removed. Use + ``django.contrib.admindocs.middleware.XViewMiddleware`` instead. + +* ``Model._meta.module_name`` was renamed to ``model_name``. + +* Remove the backward compatible shims introduced to rename ``get_query_set`` + and similar queryset methods. This affects the following classes: + ``BaseModelAdmin``, ``ChangeList``, ``BaseCommentNode``, + ``GenericForeignKey``, ``Manager``, ``SingleRelatedObjectDescriptor`` and + ``ReverseSingleRelatedObjectDescriptor``. + +* Remove the backward compatible shims introduced to rename the attributes + ``ChangeList.root_query_set`` and ``ChangeList.query_set``. + +* ``django.views.defaults.shortcut`` will be removed, as part of the + goal of removing all ``django.contrib`` references from the core + Django codebase. Instead use + ``django.contrib.contenttypes.views.shortcut``. ``django.conf.urls.shortcut`` + will also be removed. + +* Support for the Python Imaging Library (PIL) module will be removed, as it + no longer appears to be actively maintained & does not work on Python 3. + +* The following private APIs will be removed: + + - ``django.db.backend`` + - ``django.db.close_connection()`` + - ``django.db.backends.creation.BaseDatabaseCreation.set_autocommit()`` + - ``django.db.transaction.is_managed()`` + - ``django.db.transaction.managed()`` + +* ``django.forms.widgets.RadioInput`` will be removed in favor of + ``django.forms.widgets.RadioChoiceInput``. + +* The module ``django.test.simple`` and the class + ``django.test.simple.DjangoTestSuiteRunner`` will be removed. Instead use + ``django.test.runner.DiscoverRunner``. + +* The module ``django.test._doctest`` will be removed. Instead use the doctest + module from the Python standard library. + +* The ``CACHE_MIDDLEWARE_ANONYMOUS_ONLY`` setting will be removed. + +* Usage of the hard-coded *Hold down "Control", or "Command" on a Mac, to select + more than one.* string to override or append to user-provided ``help_text`` in + forms for ManyToMany model fields will not be performed by Django anymore + either at the model or forms layer. + +* The ``Model._meta.get_(add|change|delete)_permission`` methods will + be removed. + +* The session key ``django_language`` will no longer be read for backwards + compatibility. + +* Geographic Sitemaps will be removed + (``django.contrib.gis.sitemaps.views.index`` and + ``django.contrib.gis.sitemaps.views.sitemap``). + +* ``django.utils.html.fix_ampersands``, the ``fix_ampersands`` template filter and + ``django.utils.html.clean_html`` will be removed following an accelerated deprecation. + +.. _deprecation-removed-in-1.7: + +1.7 +--- + +See the :ref:`Django 1.5 release notes` for more +details on these changes. + +* The module ``django.utils.simplejson`` will be removed. The standard library + provides :mod:`json` which should be used instead. + +* The function ``django.utils.itercompat.product`` will be removed. The Python + builtin version should be used instead. + +* Auto-correction of INSTALLED_APPS and TEMPLATE_DIRS settings when they are + specified as a plain string instead of a tuple will be removed and raise an + exception. + +* The ``mimetype`` argument to the ``__init__`` methods of + :class:`~django.http.HttpResponse`, + :class:`~django.template.response.SimpleTemplateResponse`, and + :class:`~django.template.response.TemplateResponse`, will be removed. + ``content_type`` should be used instead. This also applies to the + ``render_to_response()`` shortcut and the sitemap views, + :func:`~django.contrib.sitemaps.views.index` and + :func:`~django.contrib.sitemaps.views.sitemap`. + +* When :class:`~django.http.HttpResponse` is instantiated with an iterator, + or when :attr:`~django.http.HttpResponse.content` is set to an iterator, + that iterator will be immediately consumed. + +* The ``AUTH_PROFILE_MODULE`` setting, and the ``get_profile()`` method on + the User model, will be removed. + +* The ``cleanup`` management command will be removed. It's replaced by + ``clearsessions``. + +* The ``daily_cleanup.py`` script will be removed. + +* The ``depth`` keyword argument will be removed from + :meth:`~django.db.models.query.QuerySet.select_related`. + +* The undocumented ``get_warnings_state()``/``restore_warnings_state()`` + functions from :mod:`django.test.utils` and the ``save_warnings_state()``/ + ``restore_warnings_state()`` + :ref:`django.test.*TestCase ` methods are + deprecated. Use the :class:`warnings.catch_warnings` context manager + available starting with Python 2.6 instead. + +* The undocumented ``check_for_test_cookie`` method in + :class:`~django.contrib.auth.forms.AuthenticationForm` will be removed + following an accelerated deprecation. Users subclassing this form should + remove calls to this method, and instead ensure that their auth related views + are CSRF protected, which ensures that cookies are enabled. + +* The version of ``django.contrib.auth.views.password_reset_confirm()`` that + supports base36 encoded user IDs + (``django.contrib.auth.views.password_reset_confirm_uidb36``) will be + removed. If your site has been running Django 1.6 for more than + :setting:`PASSWORD_RESET_TIMEOUT_DAYS`, this change will have no effect. If + not, then any password reset links generated before you upgrade to Django 1.7 + won't work after the upgrade. + +* The ``django.utils.encoding.StrAndUnicode`` mix-in will be removed. + Define a ``__str__`` method and apply the + :func:`~django.utils.encoding.python_2_unicode_compatible` decorator instead. + +.. _deprecation-removed-in-1.6: + +1.6 +--- + +See the :ref:`Django 1.4 release notes` for more +details on these changes. + +* ``django.contrib.databrowse`` will be removed. + +* ``django.contrib.localflavor`` will be removed following an accelerated + deprecation. + +* ``django.contrib.markup`` will be removed following an accelerated + deprecation. + +* The compatibility modules ``django.utils.copycompat`` and + ``django.utils.hashcompat`` as well as the functions + ``django.utils.itercompat.all`` and ``django.utils.itercompat.any`` will + be removed. The Python builtin versions should be used instead. + +* The ``csrf_response_exempt`` and ``csrf_view_exempt`` decorators will + be removed. Since 1.4 ``csrf_response_exempt`` has been a no-op (it + returns the same function), and ``csrf_view_exempt`` has been a + synonym for ``django.views.decorators.csrf.csrf_exempt``, which should + be used to replace it. + +* The ``django.core.cache.backends.memcached.CacheClass`` backend + was split into two in Django 1.3 in order to introduce support for + PyLibMC. The historical ``CacheClass`` will be removed in favor of + ``django.core.cache.backends.memcached.MemcachedCache``. + +* The UK-prefixed objects of ``django.contrib.localflavor.uk`` will only + be accessible through their GB-prefixed names (GB is the correct + ISO 3166 code for United Kingdom). + +* The ``IGNORABLE_404_STARTS`` and ``IGNORABLE_404_ENDS`` settings have been + superseded by :setting:`IGNORABLE_404_URLS` in the 1.4 release. They will be + removed. + +* The form wizard has been refactored to use class-based views with pluggable + backends in 1.4. The previous implementation will be removed. + +* Legacy ways of calling + :func:`~django.views.decorators.cache.cache_page` will be removed. + +* The backward-compatibility shim to automatically add a debug-false + filter to the ``'mail_admins'`` logging handler will be removed. The + :setting:`LOGGING` setting should include this filter explicitly if + it is desired. + +* The builtin truncation functions ``django.utils.text.truncate_words()`` + and ``django.utils.text.truncate_html_words()`` will be removed in + favor of the ``django.utils.text.Truncator`` class. + +* The ``django.contrib.gis.geoip.GeoIP`` class was moved to + ``django.contrib.gis.geoip`` in 1.4 -- the shortcut in + ``django.contrib.gis.utils`` will be removed. + +* ``django.conf.urls.defaults`` will be removed. The functions + ``include()``, ``patterns()``, and ``url()``, plus + :data:`~django.conf.urls.handler404` and :data:`~django.conf.urls.handler500` + are now available through ``django.conf.urls``. + +* The functions ``setup_environ()`` and ``execute_manager()`` will be removed + from :mod:`django.core.management`. This also means that the old (pre-1.4) + style of :file:`manage.py` file will no longer work. + +* Setting the ``is_safe`` and ``needs_autoescape`` flags as attributes of + template filter functions will no longer be supported. + +* The attribute ``HttpRequest.raw_post_data`` was renamed to ``HttpRequest.body`` + in 1.4. The backward compatibility will be removed -- + ``HttpRequest.raw_post_data`` will no longer work. + +* The value for the ``post_url_continue`` parameter in + ``ModelAdmin.response_add()`` will have to be either ``None`` (to redirect + to the newly created object's edit page) or a pre-formatted url. String + formats, such as the previous default ``'../%s/'``, will not be accepted any + more. + +.. _deprecation-removed-in-1.5: + +1.5 +--- + +See the :ref:`Django 1.3 release notes` for more +details on these changes. + +* Starting Django without a :setting:`SECRET_KEY` will result in an exception + rather than a ``DeprecationWarning``. (This is accelerated from the usual + deprecation path; see the :doc:`Django 1.4 release notes`.) + +* The ``mod_python`` request handler will be removed. The ``mod_wsgi`` + handler should be used instead. + +* The ``template`` attribute on ``django.test.client.Response`` + objects returned by the :ref:`test client ` will be removed. + The :attr:`~django.test.Response.templates` attribute should be + used instead. + +* The ``django.test.simple.DjangoTestRunner`` will be removed. + Instead use a ``unittest``-native class. The features of the + ``django.test.simple.DjangoTestRunner`` (including fail-fast and + Ctrl-C test termination) can be provided by :class:`unittest.TextTestRunner`. + +* The undocumented function + ``django.contrib.formtools.utils.security_hash`` will be removed, + instead use ``django.contrib.formtools.utils.form_hmac`` + +* The function-based generic view modules will be removed in favor of their + class-based equivalents, outlined :doc:`here + `. + +* The ``django.core.servers.basehttp.AdminMediaHandler`` will be + removed. In its place use + ``django.contrib.staticfiles.handlers.StaticFilesHandler``. + +* The template tags library ``adminmedia`` and the template tag ``{% + admin_media_prefix %}`` will be removed in favor of the generic static files + handling. (This is faster than the usual deprecation path; see the + :doc:`Django 1.4 release notes`.) + +* The ``url`` and ``ssi`` template tags will be modified so that the first + argument to each tag is a template variable, not an implied string. In 1.4, + this behavior is provided by a version of the tag in the ``future`` template + tag library. + +* The ``reset`` and ``sqlreset`` management commands will be removed. + +* Authentication backends will need to support an inactive user + being passed to all methods dealing with permissions. + The ``supports_inactive_user`` attribute will no longer be checked + and can be removed from custom backends. + +* :meth:`~django.contrib.gis.geos.GEOSGeometry.transform` will raise + a :class:`~django.contrib.gis.geos.GEOSException` when called + on a geometry with no SRID value. + +* ``django.http.CompatCookie`` will be removed in favor of + ``django.http.SimpleCookie``. + +* ``django.core.context_processors.PermWrapper`` and + ``django.core.context_processors.PermLookupDict`` will be removed in + favor of the corresponding + ``django.contrib.auth.context_processors.PermWrapper`` and + ``django.contrib.auth.context_processors.PermLookupDict``, respectively. + +* The :setting:`MEDIA_URL` or :setting:`STATIC_URL` settings will be + required to end with a trailing slash to ensure there is a consistent + way to combine paths in templates. + +* ``django.db.models.fields.URLField.verify_exists`` will be removed. The + feature was deprecated in 1.3.1 due to intractable security and + performance issues and will follow a slightly accelerated deprecation + timeframe. + +* Translations located under the so-called *project path* will be ignored during + the translation building process performed at runtime. The + :setting:`LOCALE_PATHS` setting can be used for the same task by including the + filesystem path to a ``locale`` directory containing non-app-specific + translations in its value. + +* The Markup contrib app will no longer support versions of Python-Markdown + library earlier than 2.1. An accelerated timeline was used as this was + a security related deprecation. + +* The ``CACHE_BACKEND`` setting will be removed. The cache backend(s) should be + specified in the :setting:`CACHES` setting. + +.. _deprecation-removed-in-1.4: + +1.4 +--- + +See the :ref:`Django 1.2 release notes` for more +details on these changes. + +* ``CsrfResponseMiddleware`` and ``CsrfMiddleware`` will be removed. Use + the ``{% csrf_token %}`` template tag inside forms to enable CSRF + protection. ``CsrfViewMiddleware`` remains and is enabled by default. + +* The old imports for CSRF functionality (``django.contrib.csrf.*``), + which moved to core in 1.2, will be removed. + +* The ``django.contrib.gis.db.backend`` module will be removed in favor + of the specific backends. + +* ``SMTPConnection`` will be removed in favor of a generic Email 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 will have to support multiple databases. + +* 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()``), will be removed. The + :doc:`messages framework ` should be used + instead. The related ``messages`` variable returned by the + auth context processor will also be removed. Note that this + means that the admin application will depend on the messages + context processor. + +* Authentication backends will need to support the ``obj`` parameter for + permission checking. The ``supports_object_permissions`` attribute + will no longer be checked and can be removed from custom backends. + +* Authentication backends will need to support the ``AnonymousUser`` class + being passed to all methods dealing with permissions. The + ``supports_anonymous_user`` variable will no longer be checked and can be + removed from custom backends. + +* 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. + +* ``django.utils.translation.get_date_formats()`` and + ``django.utils.translation.get_partial_date_formats()``. These functions + will be removed; use the locale-aware + ``django.utils.formats.get_format()`` to get the appropriate formats. + +* In ``django.forms.fields``, the constants: ``DEFAULT_DATE_INPUT_FORMATS``, + ``DEFAULT_TIME_INPUT_FORMATS`` and + ``DEFAULT_DATETIME_INPUT_FORMATS`` will be removed. Use + ``django.utils.formats.get_format()`` to get the appropriate + formats. + +* The ability to use a function-based test runner 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`` will be removed. 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``. + +* The ``postgresql`` database backend will be removed, use the + ``postgresql_psycopg2`` backend instead. + +* The ``no`` language code will be removed and has been replaced by the + ``nb`` language code. + +* Authentication backends will need to define the boolean attribute + ``supports_inactive_user`` until version 1.5 when it will be assumed that + all backends will handle inactive users. + +* ``django.db.models.fields.XMLField`` will be removed. This was + deprecated as part of the 1.3 release. An accelerated deprecation + schedule has been used because the field hasn't performed any role + beyond that of a simple ``TextField`` since the removal of ``oldforms``. + All uses of ``XMLField`` can be replaced with ``TextField``. + +* The undocumented ``mixin`` parameter to the ``open()`` method of + ``django.core.files.storage.Storage`` (and subclasses) will be removed. + +.. _deprecation-removed-in-1.3: + +1.3 +--- + +See the :ref:`Django 1.1 release notes` for more +details on these changes. + +* ``AdminSite.root()``. This method of hooking up the admin URLs will be + removed in favor of including ``admin.site.urls``. + +* Authentication backends need to define the boolean attributes + ``supports_object_permissions`` and ``supports_anonymous_user`` until + version 1.4, at which point it will be assumed that all backends will + support these options. diff --git a/test/Django-2.1.15/docs/internals/git.txt b/test/Django-2.1.15/docs/internals/git.txt new file mode 100644 index 0000000..90ff3ff --- /dev/null +++ b/test/Django-2.1.15/docs/internals/git.txt @@ -0,0 +1,249 @@ +================================= +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 clone of +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: https://www.djangoproject.com/download/ + +High-level overview +=================== + +The Django source code repository uses `Git`_ to track changes to the code +over time, so you'll need a copy of the Git client (a program called ``git``) +on your computer, and you'll want to familiarize yourself with the basics of +how Git works. + +Git's website offers downloads for various operating systems. The site also +contains vast amounts of `documentation`_. + +The Django Git repository is located online at `github.com/django/django +`_. It contains the full source code for all +Django releases, which you can browse online. + +The Git repository includes several `branches`_: + +* ``master`` contains the main in-development code which will become + the next packaged release of Django. This is where most development + activity is focused. + +* ``stable/A.B.x`` are the branches where release preparation work happens. + They are also used for bugfix and security releases which occur as necessary + after the initial release of a feature version. + +* ``soc20XX/`` branches were used by students who worked on Django + during the 2009 and 2010 Google Summer of Code programs. + +* ``attic/`` branches were used to develop major or experimental new + features without affecting the rest of Django's code. + +The Git repository also contains `tags`_. These are the exact revisions from +which packaged Django releases were produced, since version 1.0. + +The source code for the `Djangoproject.com `_ +website can be found at `github.com/django/djangoproject.com +`_. + +.. _Git: https://git-scm.com/ +.. _documentation: https://git-scm.com/documentation +.. _branches: https://github.com/django/django/branches +.. _tags: https://github.com/django/django/tags + +The master branch +================= + +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 the master branch. + +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, test suite, packaging scripts and other miscellaneous bits. +Django's code will be present in your clone as a directory named +``django``. + +To try out the in-development code with your own applications, simply place +the directory containing your clone on your Python import path. Then +``import`` statements which look for Django will find the ``django`` module +within your clone. + +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 +`, which covers things like the preferred +coding style and how to generate and submit a patch. + +Other branches +============== + +Django uses branches to prepare for releases of Django. + +In the past when Django was hosted on Subversion, branches were also used for +feature development. Now Django is hosted on Git and feature development is +done on contributor's forks, but the Subversion feature branches remain in Git +for historical reference. + +Stable branches +--------------- + +These branches can be found in the repository as ``stable/A.B.x`` +branches and will be created right after the first alpha is tagged. + +For example, immediately after *Django 1.5 alpha 1* was tagged, the branch +``stable/1.5.x`` was created and all further work on preparing the code for the +final 1.5 release was done there. + +These branches also provide bugfix and security support as described in +:ref:`supported-versions-policy`. + +For example, after the release of Django 1.5, the branch ``stable/1.5.x`` +receives only fixes for security and critical stability bugs, which are +eventually released as Django 1.5.1 and so on, ``stable/1.4.x`` receives only +security and data loss fixes, and ``stable/1.3.x`` no longer receives any +updates. + +.. admonition:: Historical information + + This policy for handling ``stable/A.B.x`` branches was adopted starting + with the Django 1.5 release cycle. + + Previously, these branches weren't created until right after the releases + and the stabilization work occurred on the main repository branch. Thus, + no new feature development work for the next release of Django could be + committed until the final release happened. + + For example, shortly after the release of Django 1.3 the branch + ``stable/1.3.x`` was created. Official support for that release has expired, + and so it no longer receives direct maintenance from the Django project. + However, that and all other similarly named branches continue to exist, and + interested community members have occasionally used them to provide + unofficial support for old Django releases. + +Feature-development branches +---------------------------- + +.. admonition:: Historical information + + Since Django moved to Git in 2012, anyone can clone the repository and + create their own branches, alleviating the need for official branches in + the source code repository. + + The following section is mostly useful if you're exploring the repository's + history, for example if you're trying to understand how some features were + designed. + +Feature-development branches tend by their nature to be temporary. Some +produce successful features which are merged back into Django's master 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, Django used to be maintained with the Subversion revision +control system, that has no standard way of indicating this. As a workaround, +branches of Django which are closed and no longer maintained were moved into +``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 ` 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 ` which added support for + :ref:`authentication backends `. This has + been part of Django since the 0.95 release. + +* ``new-admin``: A refactoring of :doc:`Django's bundled + administrative application `. 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. + +When Django moved from Subversion to Git, the information about branch merges +wasn't preserved in the source code repository. This means that the ``master`` +branch of Django doesn't contain merge commits for the above branches. + +However, this information is `available as a grafts file`_. You can restore it +by putting the following lines in ``.git/info/grafts`` in your local clone:: + + ac64e91a0cadc57f4bc5cd5d66955832320ca7a1 553a20075e6991e7a60baee51ea68c8adc520d9a 0cb8e31823b2e9f05c4ae868c19f5f38e78a5f2e + 79e68c225b926302ebb29c808dda8afa49856f5c d0f57e7c7385a112cb9e19d314352fc5ed5b0747 aa239e3e5405933af6a29dac3cf587b59a099927 + 5cf8f684237ab5addaf3549b2347c3adf107c0a7 cb45fd0ae20597306cd1f877efc99d9bd7cbee98 e27211a0deae2f1d402537f0ebb64ad4ccf6a4da + f69cf70ed813a8cd7e1f963a14ae39103e8d5265 d5dbeaa9be359a4c794885c2e9f1b5a7e5e51fb8 d2fcbcf9d76d5bb8a661ee73dae976c74183098b + aab3a418ac9293bb4abd7670f65d930cb0426d58 4ea7a11659b8a0ab07b0d2e847975f7324664f10 adf4b9311d5d64a2bdd58da50271c121ea22e397 + ff60c5f9de3e8690d1e86f3e9e3f7248a15397c8 7ef212af149540aa2da577a960d0d87029fd1514 45b4288bb66a3cda401b45901e85b645674c3988 + 9dda4abee1225db7a7b195b84c915fdd141a7260 4fe5c9b7ee09dc25921918a6dbb7605edb374bc9 3a7c14b583621272d4ef53061287b619ce3c290d + a19ed8aea395e8e07164ff7d85bd7dff2f24edca dc375fb0f3b7fbae740e8cfcd791b8bccb8a4e66 42ea7a5ce8aece67d16c6610a49560c1493d4653 + 9c52d56f6f8a9cdafb231adf9f4110473099c9b5 c91a30f00fd182faf8ca5c03cd7dbcf8b735b458 4a5c5c78f2ecd4ed8859cd5ac773ff3a01bccf96 + 953badbea5a04159adbfa970f5805c0232b6a401 4c958b15b250866b70ded7d82aa532f1e57f96ae 5664a678b29ab04cad425c15b2792f4519f43928 + 471596fc1afcb9c6258d317c619eaf5fd394e797 4e89105d64bb9e04c409139a41e9c7aac263df4c 3e9035a9625c8a8a5e88361133e87ce455c4fc13 + 9233d0426537615e06b78d28010d17d5a66adf44 6632739e94c6c38b4c5a86cf5c80c48ae50ac49f 18e151bc3f8a85f2766d64262902a9fcad44d937 + +.. _available as a grafts file: https://github.com/ramiro/django-git-grafts + +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 ``attic``. + +Finally, the repository contains ``soc2009/xxx`` and ``soc2010/xxx`` feature +branches, used for the 2009 and 2010 Google Summer of Code projects. + +Tags +==== + +Each Django release is tagged and signed by the releaser. + +The tags can be found on GitHub's `tags`_ page. + +.. _tags: https://github.com/django/django/tags diff --git a/test/Django-2.1.15/docs/internals/howto-release-django.txt b/test/Django-2.1.15/docs/internals/howto-release-django.txt new file mode 100644 index 0000000..d11b34c --- /dev/null +++ b/test/Django-2.1.15/docs/internals/howto-release-django.txt @@ -0,0 +1,434 @@ +===================== +How is Django Formed? +===================== + +.. highlight:: console + +This document explains how to release Django. + +**Please, keep these instructions up-to-date if you make changes!** The point +here is to be descriptive, not prescriptive, so feel free to streamline or +otherwise make changes, but **update this document accordingly!** + +Overview +======== + +There are three types of releases that you might need to make: + +* Security releases: disclosing and fixing a vulnerability. This'll + generally involve two or three simultaneous releases -- e.g. + 1.5.x, 1.6.x, and, depending on timing, perhaps a 1.7 alpha/beta/rc. + +* Regular version releases: either a final release (e.g. 1.5) or a + bugfix update (e.g. 1.5.1). + +* Pre-releases: e.g. 1.6 alpha, beta, or rc. + +The short version of the steps involved is: + +#. If this is a security release, pre-notify the security distribution list + one week before the actual release. + +#. Proofread the release notes, looking for organization and writing errors. + Draft a blog post and email announcement. + +#. Update version numbers and create the release package(s). + +#. Upload the package(s) to the ``djangoproject.com`` server. + +#. Upload the new version(s) to PyPI. + +#. Declare the new version in the admin on ``djangoproject.com``. + +#. Post the blog entry and send out the email announcements. + +#. Update version numbers post-release. + +There are a lot of details, so please read on. + +Prerequisites +============= + +You'll need a few things before getting started: + +* A GPG key. If the key you want to use is not your default signing key, you'll + need to add ``-u you@example.com`` to every GPG signing command below, where + ``you@example.com`` is the email address associated with the key you want to + use. + +* An install of some required Python packages:: + + $ pip install wheel twine + +* Access to Django's record on PyPI. Create a file with your credentials: + + .. code-block:: ini + :caption: ~/.pypirc + + [pypi] + username:YourUsername + password:YourPassword + +* Access to the ``djangoproject.com`` server to upload files. + +* Access to the admin on ``djangoproject.com`` as a "Site maintainer". + +* Access to post to ``django-announce``. + +* If this is a security release, access to the pre-notification distribution + list. + +If this is your first release, you'll need to coordinate with another releaser +to get all these things lined up. + +Pre-release tasks +================= + +A few items need to be taken care of before even beginning the release process. +This stuff starts about a week before the release; most of it can be done +any time leading up to the actual release: + +#. If this is a security release, send out pre-notification **one week** before + the release. We maintain a list of who gets these pre-notification emails in + the private ``django-core`` repository. Send the mail to + ``security@djangoproject.com`` and BCC the pre-notification recipients. + This email should be signed by the key you'll use for the release and + should include `CVE IDs `_ (requested with + Vendor: djangoproject, Product: django) and patches for each issue being + fixed. Also, :ref:`notify django-announce ` of the + upcoming security release. + +#. As the release approaches, watch Trac to make sure no release blockers + are left for the upcoming release. + +#. Check with the other committers to make sure they don't have any + uncommitted changes for the release. + +#. Proofread the release notes, including looking at the online + version to catch any broken links or reST errors, and make sure the + release notes contain the correct date. + +#. Double-check that the release notes mention deprecation timelines + for any APIs noted as deprecated, and that they mention any changes + in Python version support. + +#. Double-check that the release notes index has a link to the notes + for the new release; this will be in ``docs/releases/index.txt``. + +#. If this is a feature release, ensure translations from Transifex have been + integrated. This is typically done by a separate translation's manager + rather than the releaser, but here are the steps. Provided you have an + account on Transifex:: + + $ python scripts/manage_translations.py fetch + + and then commit the changed/added files (both .po and .mo). Sometimes there + are validation errors which need to be debugged, so avoid doing this task + immediately before a release is needed. + +#. :ref:`Update the django-admin manual page `:: + + $ cd docs + $ make man + $ man _build/man/django-admin.1 # do a quick sanity check + $ cp _build/man/django-admin.1 man/django-admin.1 + + and then commit the changed man page. + +Preparing for release +===================== + +Write the announcement blog post for the release. You can enter it into the +admin at any time and mark it as inactive. Here are a few examples: `example +security release announcement`__, `example regular release announcement`__, +`example pre-release announcement`__. + +__ https://www.djangoproject.com/weblog/2013/feb/19/security/ +__ https://www.djangoproject.com/weblog/2012/mar/23/14/ +__ https://www.djangoproject.com/weblog/2012/nov/27/15-beta-1/ + +Actually rolling the release +============================ + +OK, this is the fun part, where we actually push out a release! + +#. Check `Jenkins`__ is green for the version(s) you're putting out. You + probably shouldn't issue a release until it's green. + + __ https://djangoci.com + +#. A release always begins from a release branch, so you should make sure + you're on a stable branch and up-to-date. For example:: + + $ git checkout stable/1.5.x + $ git pull + +#. If this is a security release, merge the appropriate patches from + ``django-security``. Rebase these patches as necessary to make each one a + simple commit on the release branch rather than a merge commit. To ensure + this, merge them with the ``--ff-only`` flag; for example:: + + $ git checkout stable/1.5.x + $ git merge --ff-only security/1.5.x + + (This assumes ``security/1.5.x`` is a branch in the ``django-security`` repo + containing the necessary security patches for the next release in the 1.5 + series.) + + If git refuses to merge with ``--ff-only``, switch to the security-patch + branch and rebase it on the branch you are about to merge it into (``git + checkout security/1.5.x; git rebase stable/1.5.x``) and then switch back and + do the merge. Make sure the commit message for each security fix explains + that the commit is a security fix and that an announcement will follow + (:commit:`example security commit `). + +#. For a feature release, remove the ``UNDER DEVELOPMENT`` header at the + top of the release notes and add the release date on the next line. For a + patch release, replace ``*Under Development*`` with the release date. Make + this change on all branches where the release notes for a particular version + are located. + +#. Update the version number in ``django/__init__.py`` for the release. + Please see `notes on setting the VERSION tuple`_ below for details + on ``VERSION``. + +#. If this is a pre-release package, update the "Development Status" trove + classifier in ``setup.py`` to reflect this. Otherwise, make sure the + classifier is set to ``Development Status :: 5 - Production/Stable``. + +#. Tag the release using ``git tag``. For example:: + + $ git tag --sign --message="Tag 1.5.1" 1.5.1 + + You can check your work by running ``git tag --verify ``. + +#. Push your work, including the tag: ``git push --tags``. + +#. Make sure you have an absolutely clean tree by running ``git clean -dfx``. + +#. Run ``make -f extras/Makefile`` to generate the release packages. This will + create the release packages in a ``dist/`` directory. + +#. Generate the hashes of the release packages:: + + $ cd dist + $ md5sum * + $ sha1sum * + $ sha256sum * + +#. Create a "checksums" file, ``Django-<>.checksum.txt`` containing + the hashes and release information. Start with this template and insert the + correct version, date, GPG key ID (from + ``gpg --list-keys --keyid-format LONG``), release URL, and checksums: + + .. code-block:: text + + This file contains MD5, SHA1, and SHA256 checksums for the source-code + tarball and wheel files of Django <>, released <>. + + To use this file, you will need a working install of PGP or other + compatible public-key encryption software. You will also need to have + the Django release manager's public key in your keyring; this key has + the ID ``XXXXXXXXXXXXXXXX`` and can be imported from the MIT + keyserver. For example, if using the open-source GNU Privacy Guard + implementation of PGP: + + gpg --keyserver pgp.mit.edu --recv-key XXXXXXXXXXXXXXXX + + Once the key is imported, verify this file:: + + gpg --verify <> + + Once you have verified this file, you can use normal MD5, SHA1, or SHA256 + checksumming applications to generate the checksums of the Django + package and compare them to the checksums listed below. + + Release packages: + ================= + + https://www.djangoproject.com/m/releases/<> + https://www.djangoproject.com/m/releases/<> + + MD5 checksums: + ============== + + <> <> + <> <> + + SHA1 checksums: + =============== + + <> <> + <> <> + + SHA256 checksums: + ================= + + <> <> + <> <> + +#. Sign the checksum file (``gpg --clearsign --digest-algo SHA256 + Django-.checksum.txt``). This generates a signed document, + ``Django-.checksum.txt.asc`` which you can then verify using ``gpg + --verify Django-.checksum.txt.asc``. + +If you're issuing multiple releases, repeat these steps for each release. + +Making the release(s) available to the public +============================================= + +Now you're ready to actually put the release out there. To do this: + +#. Upload the release package(s) to the djangoproject server, replacing + A.B. with the appropriate version number, e.g. 1.5 for a 1.5.x release:: + + $ scp Django-* djangoproject.com:/home/www/www/media/releases/A.B + +#. Upload the checksum file(s):: + + $ scp Django-A.B.C.checksum.txt.asc djangoproject.com:/home/www/www/media/pgp/Django-A.B.C.checksum.txt + +#. Test that the release packages install correctly using ``easy_install`` + and ``pip``. Here's one method (which requires `virtualenvwrapper`__):: + + $ RELEASE_VERSION='1.7.2' + $ MAJOR_VERSION=`echo $RELEASE_VERSION| cut -c 1-3` + + $ mktmpenv + $ easy_install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz + $ deactivate + $ mktmpenv + $ pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION.tar.gz + $ deactivate + $ mktmpenv + $ pip install https://www.djangoproject.com/m/releases/$MAJOR_VERSION/Django-$RELEASE_VERSION-py3-none-any.whl + $ deactivate + + This just tests that the tarballs are available (i.e. redirects are up) and + that they install correctly, but it'll catch silly mistakes. + + __ https://pypi.org/project/virtualenvwrapper/ + +#. Ask a few people on IRC to verify the checksums by visiting the checksums + file (e.g. https://www.djangoproject.com/m/pgp/Django-1.5b1.checksum.txt) + and following the instructions in it. For bonus points, they can also unpack + the downloaded release tarball and verify that its contents appear to be + correct (proper version numbers, no stray ``.pyc`` or other undesirable + files). + +#. Upload the release packages to PyPI (for pre-releases, only upload the wheel + file):: + + $ twine upload -s dist/* + +#. Go to the `Add release page in the admin`__, enter the new release number + exactly as it appears in the name of the tarball (Django-.tar.gz). + So for example enter "1.5.1" or "1.4c2", etc. If the release is part of + an LTS branch, mark it so. + + __ https://www.djangoproject.com/admin/releases/release/add/ + +#. Make the blog post announcing the release live. + +#. For a new version release (e.g. 1.5, 1.6), update the default stable version + of the docs by flipping the ``is_default`` flag to ``True`` on the + appropriate ``DocumentRelease`` object in the ``docs.djangoproject.com`` + database (this will automatically flip it to ``False`` for all + others); you can do this using the site's admin. + + Create new ``DocumentRelease`` objects for each language that has an entry + for the previous release. Update djangoproject.com's `robots.docs.txt`__ + file by copying entries from the previous release. + + __ https://github.com/django/djangoproject.com/blob/master/djangoproject/static/robots.docs.txt + +#. Post the release announcement to the |django-announce|, |django-developers|, + and |django-users| mailing lists. This should include a link to the + announcement blog post. If this is a security release, also include + oss-security@lists.openwall.com. + +#. Add a link to the blog post in the topic of the `#django` IRC channel: + ``/msg chanserv TOPIC #django new topic goes here``. + +Post-release +============ + +You're almost done! All that's left to do now is: + +#. Update the ``VERSION`` tuple in ``django/__init__.py`` again, + incrementing to whatever the next expected release will be. For + example, after releasing 1.5.1, update ``VERSION`` to + ``VERSION = (1, 5, 2, 'alpha', 0)``. + +#. Add the release in `Trac's versions list`_ if necessary (and make it the + default if it's a final release). Not all versions are declared; + take example on previous releases. + +#. If this was a security release, update :doc:`/releases/security` with + details of the issues addressed. + +.. _Trac's versions list: https://code.djangoproject.com/admin/ticket/versions + +New stable branch tasks +======================= + +There are several items to do in the time following the creation of a new +stable branch (often following an alpha release). Some of these tasks don't +need to be done by the releaser. + +#. Create a new ``DocumentRelease`` object in the ``docs.djangoproject.com`` + database for the new version's docs, and update the + ``docs/fixtures/doc_releases.json`` JSON fixture, so people without access + to the production DB can still run an up-to-date copy of the docs site. + +#. Create a stub release note for the new feature version. Use the stub from + the previous feature release version or copy the contents from the previous + feature version and delete most of the contents leaving only the headings. + +#. Increase the default PBKDF2 iterations in + ``django.contrib.auth.hashers.PBKDF2PasswordHasher`` by about 20% + (pick a round number). Run the tests, and update the 3 failing + hasher tests with the new values. Make sure this gets noted in the + release notes (see the 1.8 release notes for an example). + +#. Remove features that have reached the end of their deprecation cycle. Each + removal should be done in a separate commit for clarity. In the commit + message, add a "refs #XXXX" to the original ticket where the deprecation + began if possible. + +#. Remove ``.. versionadded::``, ``.. versionadded::``, and ``.. deprecated::`` + annotations in the documentation from two releases ago. For example, in + Django 1.9, notes for 1.7 will be removed. + +#. Add the new branch to `Read the Docs + `_. Since the automatically + generated version names ("stable-A.B.x") differ from the version numbers + we've used historically in Read the Docs ("A.B.x"), we currently ask Eric + Holscher to add the version for us. Someday the alias functionality may be + built-in to the Read the Docs UI. + +Notes on setting the VERSION tuple +================================== + +Django's version reporting is controlled by the ``VERSION`` tuple in +``django/__init__.py``. This is a five-element tuple, whose elements +are: + +#. Major version. +#. Minor version. +#. Micro version. +#. Status -- can be one of "alpha", "beta", "rc" or "final". +#. Series number, for alpha/beta/RC packages which run in sequence + (allowing, for example, "beta 1", "beta 2", etc.). + +For a final release, the status is always "final" and the series +number is always 0. A series number of 0 with an "alpha" status will +be reported as "pre-alpha". + +Some examples: + +* ``(1, 2, 1, 'final', 0)`` → "1.2.1" + +* ``(1, 3, 0, 'alpha', 0)`` → "1.3 pre-alpha" + +* ``(1, 3, 0, 'beta', 2)`` → "1.3 beta 2" diff --git a/test/Django-2.1.15/docs/internals/index.txt b/test/Django-2.1.15/docs/internals/index.txt new file mode 100644 index 0000000..b76696a --- /dev/null +++ b/test/Django-2.1.15/docs/internals/index.txt @@ -0,0 +1,18 @@ +================ +Django internals +================ + +Documentation for people hacking on Django itself. This is the place to go if +you'd like to help improve Django or learn about how Django is managed. + +.. toctree:: + :maxdepth: 2 + + contributing/index + mailing-lists + organization + security + release-process + deprecation + git + howto-release-django diff --git a/test/Django-2.1.15/docs/internals/mailing-lists.txt b/test/Django-2.1.15/docs/internals/mailing-lists.txt new file mode 100644 index 0000000..d5b9ab5 --- /dev/null +++ b/test/Django-2.1.15/docs/internals/mailing-lists.txt @@ -0,0 +1,126 @@ +============= +Mailing lists +============= + +.. Important:: + + Please report security issues **only** to + security@djangoproject.com. This is a private list only open to + long-time, highly trusted Django developers, and its archives are + not public. For further details, please see :doc:`our security + policies `. + +Django has several official mailing lists on Google Groups that are open to +anyone. + +.. _django-users-mailing-list: + +``django-users`` +================ + +This is the right place if you are looking to ask any question regarding the +installation, usage, or debugging of Django. + +.. note:: + + If it's the first time you send an email to this list, your email must be + accepted first so don't worry if :ref:`your message does not appear + ` instantly. + +* `django-users mailing archive`_ +* `django-users subscription email address`_ +* `django-users posting email`_ + +.. _django-users mailing archive: https://groups.google.com/d/forum/django-users +.. _django-users subscription email address: mailto:django-users+subscribe@googlegroups.com +.. _django-users posting email: mailto:django-users@googlegroups.com + +.. _django-core-mentorship-mailing-list: + +``django-core-mentorship`` +========================== + +The Django Core Mentorship list is intended to provide a welcoming +introductory environment for community members interested in contributing to +the Django Project. + +* `django-core-mentorship mailing archive`_ +* `django-core-mentorship subscription email address`_ +* `django-core-mentorship posting email`_ + +.. _django-core-mentorship mailing archive: https://groups.google.com/d/forum/django-core-mentorship +.. _django-core-mentorship subscription email address: mailto:django-core-mentorship+subscribe@googlegroups.com +.. _django-core-mentorship posting email: mailto:django-core-mentorship@googlegroups.com + +.. _django-developers-mailing-list: + +``django-developers`` +===================== + +The discussion about the development of Django itself takes place here. + +Before asking a question about how to contribute, read +:doc:`/internals/contributing/index`. Many frequently asked questions are +answered there. + +.. note:: + + Please make use of + :ref:`django-users mailing list ` if you want + to ask for tech support, doing so in this list is inappropriate. + +* `django-developers mailing archive`_ +* `django-developers subscription email address`_ +* `django-developers posting email`_ + +.. _django-developers mailing archive: https://groups.google.com/d/forum/django-developers +.. _django-developers subscription email address: mailto:django-developers+subscribe@googlegroups.com +.. _django-developers posting email: mailto:django-developers@googlegroups.com + +.. _django-i18n-mailing-list: + +``django-i18n`` +=============== + +This is the place to discuss the internationalization and localization of +Django's components. + +* `django-i18n mailing archive`_ +* `django-i18n subscription email address`_ +* `django-i18n posting email`_ + +.. _django-i18n mailing archive: https://groups.google.com/d/forum/django-i18n +.. _django-i18n subscription email address: mailto:django-i18n+subscribe@googlegroups.com +.. _django-i18n posting email: mailto:django-i18n@googlegroups.com + +.. _django-announce-mailing-list: + +``django-announce`` +=================== + +A (very) low-traffic list for announcing :ref:`upcoming security releases +`, new releases of Django, and security advisories. + +* `django-announce mailing archive`_ +* `django-announce subscription email address`_ +* `django-announce posting email`_ + +.. _django-announce mailing archive: https://groups.google.com/d/forum/django-announce +.. _django-announce subscription email address: mailto:django-announce+subscribe@googlegroups.com +.. _django-announce posting email: mailto:django-announce@googlegroups.com + +.. _django-updates-mailing-list: + +``django-updates`` +================== + +All the ticket updates are mailed automatically to this list, which is tracked +by developers and interested community members. + +* `django-updates mailing archive`_ +* `django-updates subscription email address`_ +* `django-updates posting email`_ + +.. _django-updates mailing archive: https://groups.google.com/d/forum/django-updates +.. _django-updates subscription email address: mailto:django-updates+subscribe@googlegroups.com +.. _django-updates posting email: mailto:django-updates@googlegroups.com