Re: [RFC] stdcxx release process, second draft
Travis Vitek wrote:
Travis Vitek wrote
Martin Sebor wrote:
I've incorporated everyone's feedback and committed an updated
version with a number of enhancements of my own. Among the most
important are the new Goals section with suggested frequencies of
releases, and the integration of the Version Policy (I plan to delete
versions.html). Let me know what you think.
http://incubator.apache.org/stdcxx/releases.html
Martin,
I found this page that documents a few do's and dont's of binary
compatibility. I realize that most of the tricky issues involve inline
functions or templates, but this gives a list of the common pitfalls.
http://tinyurl.com/2gf38p
Travis
Here are some examples that I came up with. Each case is written in a
pseudo diff format.
Excellent! See my comments below.
Travis
// neither source nor binary compatible. not source compatible
// if user might take address of member function A::f.
struct A
{
-int f() const { return 1; }
+int f(int i = 1) const { return i; }
};
// alternative is source and binary compatible. can be changed
// to a default argument in next source incompatible release.
struct A
{
int f() const { return 1; }
+ int f(int i) const { return i; }
};
// is binary compatible, but not be source compatible because
// the compiler has no way to handle A().f(1)
struct A
{
int f(long i) const { return 2; }
+ int f(unsigned i) const { return 2; }
};
I would tend to throw these in the bag of obvious no-no's.
// not binary compatible, changing access specifier on windows is a
no-no. if the
// new access modifier is more restricted, this may be source
incompatible, but
// only if the user code calls or takes the address of the function.
class A
{
-private:
+public:
int f() const { return 1; }
};
This one is much less obvious and so it might be worth mentioning
in the document.
// source and binary compatible, not functionally compatible. f() will
square v
// in user code, and ctor will square v in library code. if an instance
is
// created in library and passed to user code, it will be squared
twice. if the
// other way, it will not be squared at all.
//
// if the definitions were outlined, this would be compatible.
class A
{
public:
-A(float f) : v(f) { }
-float f() const { return v*v; }
+A(float f) : v(f*f) { }
+float f() const { return v; }
private:
float v;
};
This is an interesting case. Why (when) does it matter that the result
of f() is different? What does it mean for STDCXX-226?
// binary and source compatible, but not functionally compatible
// because call to g() is inlined.
//
// this would be compatible if f() were outlined, or g() behaved
// the same for input values 2 and 3.
struct A
{
-void f() { g(2); }
+void f() { g(3); }
void g(int i);
};
Same as above.
// it appears that this could be fully compatible in some cases.
// it might not be source/functionally compatible if the user is
// exposed to this type. a switch on an E instance might cause a
// default block to be hit, which could trigger a failure in user
// code.
//
// if A::Z is used as a `last enum' marker, this might introduce
// a binary compatibility issue if a global or member array is
// declared to have A::Z elements.
//
// this might also be binary incompatible if the enum is persisted.
struct A
{
-enum E { W, X, Z };
+enum E { W, X, Y, Z };
};
I'd say this is both source and binary incompatible.
Consider:
switch (e) {
case A::Z: break;
case 4:break; // okay in version 1 but error on version 2
}
and:
template int struct S { };
void foo (SA::Z()); // == mangled as foo_S_A_2 in version 1
// but foo_S_A_3 in version 2
Thanks again. These are exactly the kind of examples I was hoping for:
innocuous looking changes that are fully compatible in most situations
but can be actually be breaking in some edge cases.
Martin
Re: [RFC] stdcxx release process, second draft
The Linux Documentation Project lists a number of examples of library
incompatibilities:
http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN135
--Mark
On Dec 13, 2007 4:44 PM, Martin Sebor [EMAIL PROTECTED] wrote:
Travis Vitek wrote:
Travis Vitek wrote
Martin Sebor wrote:
I've incorporated everyone's feedback and committed an updated
version with a number of enhancements of my own. Among the most
important are the new Goals section with suggested frequencies of
releases, and the integration of the Version Policy (I plan to delete
versions.html). Let me know what you think.
http://incubator.apache.org/stdcxx/releases.html
Martin,
I found this page that documents a few do's and dont's of binary
compatibility. I realize that most of the tricky issues involve inline
functions or templates, but this gives a list of the common pitfalls.
http://tinyurl.com/2gf38p
Travis
Here are some examples that I came up with. Each case is written in a
pseudo diff format.
Excellent! See my comments below.
Travis
// neither source nor binary compatible. not source compatible
// if user might take address of member function A::f.
struct A
{
-int f() const { return 1; }
+int f(int i = 1) const { return i; }
};
// alternative is source and binary compatible. can be changed
// to a default argument in next source incompatible release.
struct A
{
int f() const { return 1; }
+ int f(int i) const { return i; }
};
// is binary compatible, but not be source compatible because
// the compiler has no way to handle A().f(1)
struct A
{
int f(long i) const { return 2; }
+ int f(unsigned i) const { return 2; }
};
I would tend to throw these in the bag of obvious no-no's.
// not binary compatible, changing access specifier on windows is a
no-no. if the
// new access modifier is more restricted, this may be source
incompatible, but
// only if the user code calls or takes the address of the function.
class A
{
-private:
+public:
int f() const { return 1; }
};
This one is much less obvious and so it might be worth mentioning
in the document.
// source and binary compatible, not functionally compatible. f() will
square v
// in user code, and ctor will square v in library code. if an instance
is
// created in library and passed to user code, it will be squared
twice. if the
// other way, it will not be squared at all.
//
// if the definitions were outlined, this would be compatible.
class A
{
public:
-A(float f) : v(f) { }
-float f() const { return v*v; }
+A(float f) : v(f*f) { }
+float f() const { return v; }
private:
float v;
};
This is an interesting case. Why (when) does it matter that the result
of f() is different? What does it mean for STDCXX-226?
// binary and source compatible, but not functionally compatible
// because call to g() is inlined.
//
// this would be compatible if f() were outlined, or g() behaved
// the same for input values 2 and 3.
struct A
{
-void f() { g(2); }
+void f() { g(3); }
void g(int i);
};
Same as above.
// it appears that this could be fully compatible in some cases.
// it might not be source/functionally compatible if the user is
// exposed to this type. a switch on an E instance might cause a
// default block to be hit, which could trigger a failure in user
// code.
//
// if A::Z is used as a `last enum' marker, this might introduce
// a binary compatibility issue if a global or member array is
// declared to have A::Z elements.
//
// this might also be binary incompatible if the enum is persisted.
struct A
{
-enum E { W, X, Z };
+enum E { W, X, Y, Z };
};
I'd say this is both source and binary incompatible.
Consider:
switch (e) {
case A::Z: break;
case 4:break; // okay in version 1 but error on version 2
}
and:
template int struct S { };
void foo (SA::Z()); // == mangled as foo_S_A_2 in version 1
// but foo_S_A_3 in version 2
Thanks again. These are exactly the kind of examples I was hoping for:
innocuous looking changes that are fully compatible in most situations
but can be actually be breaking in some edge cases.
Martin
RE: [RFC] stdcxx release process, second draft
The scope of this issue is rather large for a minor release...IMHO.
Brad.
-Original Message-
From: Martin Sebor [mailto:[EMAIL PROTECTED] On Behalf Of Martin Sebor
Sent: Tuesday, November 27, 2007 9:59 PM
To: stdcxx-dev@incubator.apache.org
Subject: Re: [RFC] stdcxx release process, second draft
So here's a question: do we think STDCXX-336 doable for 4.2.1?
Martin
Farid Zaripov wrote:
Martin Sebor wrote:
I've incorporated everyone's feedback and committed an
updated version
with a number of enhancements of my own. Among the most
important are
the new Goals section with suggested frequencies of
releases, and the
integration of the Version Policy (I plan to delete
versions.html).
Let me know what you think.
http://incubator.apache.org/stdcxx/releases.html
I have no objections on this document.
Here the some examples (the only source incompatible changes):
1. Source incompatible changes
1.1. Merging two or more overloaded functions/methods in one using
default parameters:
I.e. replacing void std::vector::resize (size_type) and void
std::vector::resize (size_type, value_type)
with void std::vector::resize (size_type, value_type =
value_type()).
1.2. Implementing the additional overloads (extensions) of
the standard
functions/methods:
I.e. adding std::ostream std::ostream::operator
(std::ostream,
const wchar*).
1.3. Adding some function/class in global namespace, that
may interfere
with user-defined function/class
(i.e without using '__; prefix):
I.e. adding function void print (const char* str) {
std::cout
str std::endl; } may conflict with user defined
void print (const char* str) { std::printf (%s,
str); } due to
multiple function definition.
1.4. Adding some public/protected methods not specified by standard,
that may interfere with user-defined
methods in classes, inherited from the library class.
1.5. Adding some macros that may accidentally modify the
user code: i.e.
#define new(p) malloc (p).
1.6. Moving some declarations from one header file to
another without
#including the second one in the first
may cause unknown identifier compiler error.
Farid.
Re: [RFC] stdcxx release process, second draft
Martin Sebor wrote: Martin Sebor wrote: So here's a question: do we think STDCXX-336 doable for 4.2.1? Also, what's your take on STDCXX-242 and STDCXX-343? I think there might be others where it's not completely clear (at least to me) what is forward compatible and what's not. STDCXX-343 is quite source incompatible. It is one of those weird cases that I can't imagine that a user would intentionally write, and even if they did they might not get the results that they want (undefined behavior). Travis -- View this message in context: http://www.nabble.com/-RFC--stdcxx-release-process-tf4729351.html#a14032347 Sent from the stdcxx-dev mailing list archive at Nabble.com.
Re: [RFC] stdcxx release process, second draft
Travis Vitek wrote: Martin Sebor wrote: Martin Sebor wrote: So here's a question: do we think STDCXX-336 doable for 4.2.1? Also, what's your take on STDCXX-242 and STDCXX-343? I think there might be others where it's not completely clear (at least to me) what is forward compatible and what's not. STDCXX-343 is quite source incompatible. It is one of those weird cases that I can't imagine that a user would intentionally write, and even if they did they might not get the results that they want (undefined behavior). You're right. Even if some members of std::auto_ptrvoid have undefined behavior removing the body of the whole specialization is a source incompatible change that needs to wait until at least 4.3, if not 5.0. The only reason why I think we might want to even consider removing it in 4.3 is that the existence of the specialization of the current template represents a bug in the C++ standard and (likely) also a bug in user code. Martin
RE: [RFC] stdcxx release process, second draft
Travis Vitek wrote
Martin Sebor wrote:
I've incorporated everyone's feedback and committed an updated
version with a number of enhancements of my own. Among the most
important are the new Goals section with suggested frequencies of
releases, and the integration of the Version Policy (I plan to delete
versions.html). Let me know what you think.
http://incubator.apache.org/stdcxx/releases.html
Martin,
I found this page that documents a few do's and dont's of binary
compatibility. I realize that most of the tricky issues involve inline
functions or templates, but this gives a list of the common pitfalls.
http://tinyurl.com/2gf38p
Travis
Here are some examples that I came up with. Each case is written in a
pseudo diff format.
Travis
// neither source nor binary compatible. not source compatible
// if user might take address of member function A::f.
struct A
{
-int f() const { return 1; }
+int f(int i = 1) const { return i; }
};
// alternative is source and binary compatible. can be changed
// to a default argument in next source incompatible release.
struct A
{
int f() const { return 1; }
+ int f(int i) const { return i; }
};
// is binary compatible, but not be source compatible because
// the compiler has no way to handle A().f(1)
struct A
{
int f(long i) const { return 2; }
+ int f(unsigned i) const { return 2; }
};
// not binary compatible, changing access specifier on windows is a
no-no. if the
// new access modifier is more restricted, this may be source
incompatible, but
// only if the user code calls or takes the address of the function.
class A
{
-private:
+public:
int f() const { return 1; }
};
// source and binary compatible, not functionally compatible. f() will
square v
// in user code, and ctor will square v in library code. if an instance
is
// created in library and passed to user code, it will be squared
twice. if the
// other way, it will not be squared at all.
//
// if the definitions were outlined, this would be compatible.
class A
{
public:
-A(float f) : v(f) { }
-float f() const { return v*v; }
+A(float f) : v(f*f) { }
+float f() const { return v; }
private:
float v;
};
// binary and source compatible, but not functionally compatible
// because call to g() is inlined.
//
// this would be compatible if f() were outlined, or g() behaved
// the same for input values 2 and 3.
struct A
{
-void f() { g(2); }
+void f() { g(3); }
void g(int i);
};
// it appears that this could be fully compatible in some cases.
// it might not be source/functionally compatible if the user is
// exposed to this type. a switch on an E instance might cause a
// default block to be hit, which could trigger a failure in user
// code.
//
// if A::Z is used as a `last enum' marker, this might introduce
// a binary compatibility issue if a global or member array is
// declared to have A::Z elements.
//
// this might also be binary incompatible if the enum is persisted.
struct A
{
-enum E { W, X, Z };
+enum E { W, X, Y, Z };
};
RE: [RFC] stdcxx release process, second draft
Martin Sebor wrote:
I've incorporated everyone's feedback and committed an
updated version
with a number of enhancements of my own. Among the most
important are
the new Goals section with suggested frequencies of
releases, and the
integration of the Version Policy (I plan to delete versions.html).
Let me know what you think.
http://incubator.apache.org/stdcxx/releases.html
I have no objections on this document.
Here the some examples (the only source incompatible changes):
1. Source incompatible changes
1.1. Merging two or more overloaded functions/methods in one using
default parameters:
I.e. replacing void std::vector::resize (size_type) and void
std::vector::resize (size_type, value_type)
with void std::vector::resize (size_type, value_type = value_type()).
1.2. Implementing the additional overloads (extensions) of the standard
functions/methods:
I.e. adding std::ostream std::ostream::operator (std::ostream,
const wchar*).
1.3. Adding some function/class in global namespace, that may interfere
with user-defined function/class
(i.e without using '__; prefix):
I.e. adding function void print (const char* str) { std::cout
str std::endl; } may conflict with user defined
void print (const char* str) { std::printf (%s, str); } due to
multiple function definition.
1.4. Adding some public/protected methods not specified by standard,
that may interfere with user-defined
methods in classes, inherited from the library class.
1.5. Adding some macros that may accidentally modify the user code: i.e.
#define new(p) malloc (p).
1.6. Moving some declarations from one header file to another without
#including the second one in the first
may cause unknown identifier compiler error.
Farid.
Re: [RFC] stdcxx release process, second draft
So here's a question: do we think STDCXX-336 doable for 4.2.1?
Martin
Farid Zaripov wrote:
Martin Sebor wrote:
I've incorporated everyone's feedback and committed an
updated version
with a number of enhancements of my own. Among the most
important are
the new Goals section with suggested frequencies of
releases, and the
integration of the Version Policy (I plan to delete versions.html).
Let me know what you think.
http://incubator.apache.org/stdcxx/releases.html
I have no objections on this document.
Here the some examples (the only source incompatible changes):
1. Source incompatible changes
1.1. Merging two or more overloaded functions/methods in one using
default parameters:
I.e. replacing void std::vector::resize (size_type) and void
std::vector::resize (size_type, value_type)
with void std::vector::resize (size_type, value_type = value_type()).
1.2. Implementing the additional overloads (extensions) of the standard
functions/methods:
I.e. adding std::ostream std::ostream::operator (std::ostream,
const wchar*).
1.3. Adding some function/class in global namespace, that may interfere
with user-defined function/class
(i.e without using '__; prefix):
I.e. adding function void print (const char* str) { std::cout
str std::endl; } may conflict with user defined
void print (const char* str) { std::printf (%s, str); } due to
multiple function definition.
1.4. Adding some public/protected methods not specified by standard,
that may interfere with user-defined
methods in classes, inherited from the library class.
1.5. Adding some macros that may accidentally modify the user code: i.e.
#define new(p) malloc (p).
1.6. Moving some declarations from one header file to another without
#including the second one in the first
may cause unknown identifier compiler error.
Farid.
Re: [RFC] stdcxx release process, second draft
Martin Sebor wrote:
So here's a question: do we think STDCXX-336 doable for 4.2.1?
Also, what's your take on STDCXX-242 and STDCXX-343? I think there
might be others where it's not completely clear (at least to me)
what is forward compatible and what's not.
Martin
Farid Zaripov wrote:
Martin Sebor wrote:
I've incorporated everyone's feedback and committed an
updated version
with a number of enhancements of my own. Among the most
important are
the new Goals section with suggested frequencies of
releases, and the
integration of the Version Policy (I plan to delete versions.html).
Let me know what you think.
http://incubator.apache.org/stdcxx/releases.html
I have no objections on this document.
Here the some examples (the only source incompatible changes):
1. Source incompatible changes
1.1. Merging two or more overloaded functions/methods in one using
default parameters:
I.e. replacing void std::vector::resize (size_type) and void
std::vector::resize (size_type, value_type)
with void std::vector::resize (size_type, value_type = value_type()).
1.2. Implementing the additional overloads (extensions) of the standard
functions/methods:
I.e. adding std::ostream std::ostream::operator (std::ostream,
const wchar*).
1.3. Adding some function/class in global namespace, that may interfere
with user-defined function/class
(i.e without using '__; prefix):
I.e. adding function void print (const char* str) { std::cout
str std::endl; } may conflict with user defined
void print (const char* str) { std::printf (%s, str); } due to
multiple function definition.
1.4. Adding some public/protected methods not specified by standard,
that may interfere with user-defined
methods in classes, inherited from the library class.
1.5. Adding some macros that may accidentally modify the user code: i.e.
#define new(p) malloc (p).
1.6. Moving some declarations from one header file to another without
#including the second one in the first
may cause unknown identifier compiler error.
Farid.
Re: [RFC] stdcxx release process, second draft
Martin Sebor wrote: I've incorporated everyone's feedback and committed an updated version with a number of enhancements of my own. Among the most important are the new Goals section with suggested frequencies of releases, and the integration of the Version Policy (I plan to delete versions.html). Let me know what you think. http://incubator.apache.org/stdcxx/releases.html Martin, I found this page that documents a few do's and dont's of binary compatibility. I realize that most of the tricky issues involve inline functions or templates, but this gives a list of the common pitfalls. http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++#The_Do.27s_and_Don.27ts Travis -- View this message in context: http://www.nabble.com/-RFC--stdcxx-release-process-tf4729351.html#a13849210 Sent from the stdcxx-dev mailing list archive at Nabble.com.
RE: [RFC] stdcxx release process, second draft
Overall, I'd say it's a pretty good start. All of the major elements are there: goals/objectives, tasks/procedures, definitions/roles, etc. As it evolves though, you'll probably want to break the process definitions into two separate documents: one for the development process and one for the release process. Also, the versioning policy is currently intwined with the release process. They're closely related of course but they should be more easily distinguished. Were they separate documents at one time? Just my personal preference, but I like to see each policy statement in a separate document since a process is usually defined to enact one or more policies. I also noticed the Version Policy and Definitions are listed in the opposite order in the Index at the top from that given in the content. Brad. -Original Message- From: Martin Sebor [mailto:[EMAIL PROTECTED] Sent: Monday, November 12, 2007 9:06 PM To: stdcxx-dev@incubator.apache.org Subject: [RFC] stdcxx release process, second draft I've incorporated everyone's feedback and committed an updated version with a number of enhancements of my own. Among the most important are the new Goals section with suggested frequencies of releases, and the integration of the Version Policy (I plan to delete versions.html). Let me know what you think. http://incubator.apache.org/stdcxx/releases.html Martin Sebor wrote: I've checked in the first draft of a document outlining our release process. It should be read along with the versioning policy that was circulated earlier. I would like to integrate both into one coherent policy in the near future and put it in place for 4.2.1. http://incubator.apache.org/stdcxx/releases.html http://incubator.apache.org/stdcxx/versions.html Please respond with suggestions for changes, additions, corrections, comments, and/or questions. Thanks Martin -- View this message in context: http://www.nabble.com/-RFC--stdcxx-release-process-tf4729351.h tml#a13719498 Sent from the stdcxx-dev mailing list archive at Nabble.com.
