<commit_before>=======================================
Wagtailmenus 2.12 (alpha) release notes
=======================================

.. NOTE ::
    
    Wagtailmenus 2.12 is in the alpha stage of development. Any changes
    detailed below are subject to change before the final 2.12 release.


.. contents::
    :local:
    :depth: 1


What's new?
===========

TBA


Minor changes & bug fixes 
=========================

- Fixed an issue with the section menu in the release notes section of the docs.
- Updated tox config to test against Python 3.7 and Wagtail 2.2
- Updated Travis CI config to deploy to PyPi automatically when commits are tagged appropriately.
- Pinned django-cogwheels dependency to version 0.2 to reduce potential for backwards-incompatibility issues.


Deprecations
============

TBA


Upgrade considerations
======================

Following a standard deprecation period a two minor releases, the following functionality has now been removed.


The WAGTAILMENUS_CHILDREN_MENU_CLASS_PATH setting is no longer supported
------------------------------------------------------------------------

If you're using this to override the menu class used to render children menus in your project, you'll need to update your Django settings to use the new, shorter setting name: WAGTAILMENUS_CHILDREN_MENU_CLASS.

For example, if you had the following:

.. code-block:: python<commit_msg>Update 2.12.rst<commit_after>=======================================
Wagtailmenus 2.12 (alpha) release notes
=======================================

.. NOTE ::
    
    Wagtailmenus 2.12 is in the alpha stage of development. Any changes
    detailed below are subject to change before the final 2.12 release.


.. contents::
    :local:
    :depth: 1


What's new?
===========

TBA


Minor changes & bug fixes 
=========================

- Arabic translations added - Courtesy of @alfuhigi. Many thanks!
- Fixed an issue with the section menu in the release notes section of the docs.
- Updated tox config to test against Python 3.7 and Wagtail 2.2
- Updated Travis CI config to deploy to PyPi automatically when commits are tagged appropriately.
- Pinned django-cogwheels dependency to version 0.2 to reduce potential for backwards-incompatibility issues.
- Changed the signature of ``Menu.render_from_tag()`` to better indicate common expected/supported arguments for menus.
- Added a custom ``render_from_tag()`` method for each individual menu class, with a signature that highlights all relevant options, including those specific to that menu type.
- Renamed ``Menu.get_contextual_vals_from_context()`` to ``Menu._create_contextualvals_obj_from_context()`` to give a better
indication of what the method does.
- Renamed ``Menu.get_option_vals_from_options`` to ``Menu._create_optionvals_obj_from_values()`` to give a better indication of what the method does.


Deprecations
============

The following items have been deprecated in this release. They will continue to be supported for a standard deprecation period of two minor releases, but will be removed in version 3.0.


``Menu.get_instance_for_rendering()`` is deprecated
---------------------------------------------------

In an effort to make method names more reflective of their functionality, this method has been replaced by two methods:
``create_from_collected_values()`` and ``get_from_collected_values``. The former is implemented on menu classes that are  not model based (where an instance must be created from scratch each time, for example: ``ChildrenMenu``, ``SectionMenu``, ``SubMenu``), and the latter is implemented on model-based menu classes, where a corresponding object must be retreived from the database (so, ``AbstractMainMenu``, ``MainMenu``, ``AbstractFlatMenu`` and ``FlatMenu``). 

``render_from_tag()`` automatically calls one or the other, depending on whether the class inherits from ``django.db.models.Model``.


Upgrade considerations
======================

Following a standard deprecation period a two minor releases, the following functionality has now been removed.


The WAGTAILMENUS_CHILDREN_MENU_CLASS_PATH setting is no longer supported
------------------------------------------------------------------------

If you're using this to override the menu class used to render children menus in your project, you'll need to update your Django settings to use the new, shorter setting name: WAGTAILMENUS_CHILDREN_MENU_CLASS.

For example, if you had the following:

.. code-block:: python
{'fraction_non_alphanumeric': 0.1632562277580071, 'fraction_numerical': 0.008229537366548042, 'mean_word_length': 3.8827361563517915, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7032225', 'n_tokens_mistral': 1184, 'n_tokens_neox': 1079, 'n_words': 517}