Proposed legacy macro renaming policy (was: Re: What to do about Boost libraries which use user-defined macros which are not BOOST_ prefixed)

From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2019-12-18 13:02:42

> I think, given that PHOENIX_LIMIT is currently reserved for
> Boost.Phoenix, keeping it reserved still for the deprecation period is
> not a problem (IOW, not more of a problem than we currently have). The
> important part is that we set the transition to BOOST_PHOENIX_LIMIT in
> motion, starting with PHOENIX_LIMIT deprecation and warning the users.

Firstly I'd like to thank the majority of library maintainers who either
went ahead and fixed their non-BOOST_ prefixed libraries immediately, or
have agreed to do so when I get a sed script for them.

There is resistance however from a minority of library maintainers who
insist that this list must formally agree on a policy first. So here is
my proposed legacy macro renaming policy:

1. If a Boost library observes the setting of a non-BOOST_ prefixed
macro which is defined by other Boost code, it must be renamed.

2. If a Boost library observes the setting of a non-BOOST_ prefixed
macro which is never defined by other Boost code, it need not be renamed.

3. If a Boost library defines a non-BOOST_ prefixed macro whose value is
observed by code not under Boost control, it is not renamed.

4. For all defining of non-BOOST_ prefixed macros in publicly includable
header code, it must be renamed.

The end goal of this policy is that future Boost code will never set a
non-BOOST_ prefixed macro in public headers, except where third party
dependencies require it.

Renaming strategy can be anything the library maintainer likes. Good
suggestions were made here earlier on how best to give deprecation
warnings for the next year or two before insisting, or whether to
support multiple observable input macros etc.

There is a PR for a library test which determines if your public headers
have defined any non-BOOST_ macros at
https://github.com/boostorg/boost/pull/356. You can use this to check
your own libraries. Some whitelisting in the meta json file may be
needed for libraries which have no alternative in the case 2 situation
above. If your library is one of those, please comment which library and
why in the PR comments.

Niall