From f294b2d5054f421ccf13e110b2cc67128d4bebd8 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Thu, 16 Mar 2017 18:18:10 -0400 Subject: [PATCH] add notes about skipping log translation setup Now that we have decided to skip log translations, let's stop telling people to set them up. This change adds a note saying the work is not needed, but leaves the instructions so that someone trying to understand existing code can review them. The actual translation functions will be marked for deprecation in the future, when enough projects have dropped using them to warrant that change. Change-Id: Ia34ad79ca9c6d1ea862b6954669c992a898a03ff Signed-off-by: Doug Hellmann --- doc/source/guidelines.rst | 9 +++++++++ doc/source/usage.rst | 13 +++++++++++++ 2 files changed, 22 insertions(+) diff --git a/doc/source/guidelines.rst b/doc/source/guidelines.rst index dd82aec..9ed87fe 100644 --- a/doc/source/guidelines.rst +++ b/doc/source/guidelines.rst @@ -51,6 +51,15 @@ By default, the translation should use the ``_()``. Log Translation =============== +.. note:: + + Starting with the Pike series, OpenStack no longer supports log + translation. It is not necessary to add translation instructions to + new code, and the instructions can be removed from old code. Refer + to the email thread `understanding log domain change + `_ + on the openstack-dev mailing list for more details. + OpenStack supports translating some log levels using separate message catalogs, and so has separate marker functions. These well-known names are used by the build system jobs that extract the messages from the diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 1c92fdd..e80816e 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -27,6 +27,15 @@ the marker functions the factory creates. it is a private implementation detail, and not meant to be used outside of the library's own code. +.. note:: + + Starting with the Pike series, OpenStack no longer supports log + translation. It is not necessary to add translation instructions to + new code, and the instructions can be removed from old code. Refer + to the email thread `understanding log domain change + `_ + on the openstack-dev mailing list for more details. + .. code-block:: python # myapp/_i18n.py @@ -50,6 +59,9 @@ the marker functions the factory creates. # Translators for log levels. # + # NOTE(dhellmann): This is not needed for new projects as of the + # Pike series. + # # The abbreviated names are meant to reflect the usual use of a short # name like '_'. The "L" is for "log" and the other letter comes from # the level. @@ -118,6 +130,7 @@ code for translatable strings looks for the marker function names. :func:`gettextutils.install` should be replaced with the application or library integration module described here. + Handling hacking Objections to Imports ======================================