[cxx-abi-dev] A proposed proposal process for the Itanium ABI

[John McCall]

To all it may concern:

In order to combat the ongoing bit-rot of the Itanium ABI specification, the
folks at Mentor Graphics Sourcery Tools (née CodeSourcery) have moved
the ABI documents to github.

The github project page is here:
  https://github.com/MentorEmbedded/cxx-abi/

The living documents are here:
  http://mentorembedded.github.com/cxx-abi/

They've also blessed Matthew Markland and me with the magical powers
necessary to update the documents.  We see this as a sort of "editor"-like
responsibility.  Given that some editing needs to be done, but to avoid
ruffling any feathers that can remain unruffled, we'd like to establish some
basic rules of engagement.

(n.b. — I've cleared this email with Matthew, but any errors or perceived
rudeness should be taken as mine alone.)

I apologize for the abruptness, but:  please do not respond to this message
unless you're an Itanium-ABI tool implementor who feels that the proposed
process is significantly mistaken and/or will tend to exclude you.  Otherwise,
while I'm sure that your university is indeed a leading contributor to research
in collaborative review theory, or that your company's five year plan relies
on a thousand promises that nobody ever made that you absolutely need
our blessing for, or that you personally have a deep and passionate
commitment to the C++ language that entitles you to a commanding seat at
every table tangentially related to it— while I'm sure one or all of these things
are true, I want to make it clear that the "votes" belong to implementors,
because an ABI's not worth much if it's not really the consensus of its
implementations.  I have no doubt that everyone else's skills and opinions
will help us to guide and maintain the ABI;  right now, we need to make sure
that everyone is on board.

Here is our mission at a broad scale:  if a user has two different C++
tools (probably compilers, but let's not constrain ourselves) that target
the same platform and claim to support the Itanium ABI, then either:
 (1) the tools will interoperate correctly on correct code or
 (2) we'll have a really good reason why not and a feasible
   plan to fix it in future releases of the tools.
This should apply whether the two tools are completely independent
implementations or just two different versions of the same implementation.

Here is our mission at a small scale:  we want to develop and document
the consensus among all the C++ implementors who use the ABI.

Okay.  As we see it, there are three classes of changes we can make:

1.  An editorial change can be anything from a grammar / wording fix to
a minor clarification of intent.  The key here is that we feel that it's totally
uncontroversial and settled.  We won't bother notifying the list when we
make this kind of update, but if you're interested, you can sign up at
github for commit notifications.

2.  A minor change might be a missing case (e.g. in the mangler) or any
clarification which isn't obviously settled or uncontroversial.  For these,
we will make a point of notifying the list when making any changes.
For missing cases in particular, we will make an effort to make sure that
the change is consistent with what seems to be current practice.  If there's
significant divergence, we will post to the list for guidance before pushing
anything into the document.

I personally have access to many versions of clang, many versions of gcc,
and an increasingly old version of EDG.  If you would like me to consider
your implementation when drafting or editing proposals, you should email
me to make sure I can test it. :)

3.  A major change is anything with a serious and potentially pervasive
impact on the ABI.  Given our mission, most such changes are likely
ruled out;  however, I am counting in this category anything which
amounts to a major policy statement.  For these issues, we will attempt
to lead a conversation on the list and develop consensus, waiting at
least two weeks from the initial proposal before making any changes
to the live document.

Anyone with a suggestion (or better yet, a patch) can just email Matt or me
or both, and we'll try to, without undue delay, either push it into the
repository or forward it to this list for discussion, as we think is appropriate
by the above rubric.

If you disagree with an emerging consensus, or if you feel that a previous
change was mistaken or unfortunate, it is your responsibility to speak up.
This is an open process, and it's nobody's full-time job;  we're not going to
conduct straw polls or ring doorbells.

On an individual note, I will try not to let my role as maintainer of a specific
implementation interfere with my role as editor of the general document.
I think I've demonstrated in the past a willingness to change clang when
we were the odd ones out or otherwise in the wrong.  I hope that other
implementors are willing to reciprocate.

With all that said, we have something of a queue to get through.  Let's treat
this proposal itself as a major change;  if you have objections, please
bring them up as soon as possible so that we can work something out
in the next few weeks.  If we can all agree that this is a reasonable basic
process, then we can get started.

John.