Re: [proposal] Jakarta Deprecation Policy

[Michael McCallum]

> 
> Let us not kid ourselves, a widely distributed API is expected to be backward 
>compatible 
> over *many* major and minor versions. (The distinction between minor and major 
>versions is > 
completely arbitrary.)

The arbitrary nature of the revisions numbers is what gives us the ability to say for 
the next 
version we deprecate this. 

The changing of the revision numbers represents that the project has evolved into 
something 
more than it was. And cutting out chaff is a part of the process.

If there is a major number change then the user should expect things to be different 
thats why 
the developers decided the project needed a major revision number increment.

Making a standard practice just means that the users know how it happens and can pick 
up any 
jakarta project confidently knowing that the code they write against it will not break 
(well at least 
in compile time terms ) when the next release is made. 

Michael


-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Re: [proposal] Jakarta Deprecation Policy

[Michael McCallum]

> What I propose is that we take this document (or one similar to it) and
> migrate it up to the overall Jakarta Project instead of just being a Turbine
> policy and get all the projects to "sign" their name on it.
> 
> 
> 
> I think it would go a long way towards raising awareness of the need to
> deprecate things (thanks to Sam starting this with Gump) as well as make the
> corporate types feel more comfortable with regards to depending on "that
> Open Source Software stuff"...
> 
> Comments?

+1

A very good idea.

-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Re: [proposal] Jakarta Deprecation Policy

[Ceki Gülcü]

At 07:54 16.05.2001 -0400, you wrote:
>Jon Stevens wrote:
>> 
>> Well, there haven't been many flame wars around here recently, so let me
>> start one. I seem to be good at that. :-)
>> 
>> What I propose is that we take this document (or one similar to it) and
>> migrate it up to the overall Jakarta Project instead of just being a Turbine
>> policy and get all the projects to "sign" their name on it.
>> 
>> 
>> 
>> I think it would go a long way towards raising awareness of the need to
>> deprecate things (thanks to Sam starting this with Gump) as well as make the
>> corporate types feel more comfortable with regards to depending on "that
>> Open Source Software stuff"...
>> 
>> Comments?
>> 
>
>+1 in general, with agreement with others' remarks about it being not
>appropriate for major releases ( n.x -> (n+1).0 ) and not applicable for
>v < 1.0
>
>However I do worry about how this might subtly (or un-subtly) affect the
>development 'gestalt'.  As projects get more mature, acquire a serious
>user base, etc, doesn't this kind of thing happen as a matter of
>course?   In the few cases that it doesn't, Uncle Gumpy seems help keep
>us on the straight and narrow.
>
>If this is true, would it be just as useful to offer as a set of
>guidelines?

I think Geir has a valid point. 

I would like to add that a deprecation policy must be placed in the context of a 
particular project, in particular with respect to its stability.  In my very humble 
opinion, API stability is a very complex subject, perhaps the most involved topic in 
software engineering. As such, I don't think it is possible to give a definitive 
answer to the problem even if the deprecation policy advocated by Sam and Jon is one 
of the best practices available to us. 

Let us not kid ourselves, a widely distributed API is expected to be backward 
compatible over *many* major and minor versions. (The distinction between minor and 
major versions is completely arbitrary.)

One rather conservative approach, notably practiced in the JDK, is to never remove 
methods (or classes) but to overhaul an existing API by replacing it with totally new 
classes (or packages) without removing any existing APIs. This is what Microsoft has 
been doing with Windows, Sun with the JDK, Intel with the 80x86 instruction set, Linus 
et al. with Linux, etc. etc. This approach has the disadvantage of bloat yet I don't 
see many ways for avoiding it without being blessed by extreme and unworldly 
foresight. Just my two verbose cents. Ceki 






-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Re: [proposal] Jakarta Deprecation Policy

[Geir Magnusson Jr.]

Jon Stevens wrote:
> 
> Well, there haven't been many flame wars around here recently, so let me
> start one. I seem to be good at that. :-)
> 
> What I propose is that we take this document (or one similar to it) and
> migrate it up to the overall Jakarta Project instead of just being a Turbine
> policy and get all the projects to "sign" their name on it.
> 
> 
> 
> I think it would go a long way towards raising awareness of the need to
> deprecate things (thanks to Sam starting this with Gump) as well as make the
> corporate types feel more comfortable with regards to depending on "that
> Open Source Software stuff"...
> 
> Comments?
> 

+1 in general, with agreement with others' remarks about it being not
appropriate for major releases ( n.x -> (n+1).0 ) and not applicable for
v < 1.0

However I do worry about how this might subtly (or un-subtly) affect the
development 'gestalt'.  As projects get more mature, acquire a serious
user base, etc, doesn't this kind of thing happen as a matter of
course?   In the few cases that it doesn't, Uncle Gumpy seems help keep
us on the straight and narrow.

If this is true, would it be just as useful to offer as a set of
guidelines?

geir

-- 
Geir Magnusson Jr.   [EMAIL PROTECTED]
System and Software Consulting
Developing for the web?  See http://jakarta.apache.org/velocity/
"still climbing up to the shoulders..."

-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Re: [proposal] Jakarta Deprecation Policy

[Remy Maucherat]

> Well, there haven't been many flame wars around here recently, so let me
> start one. I seem to be good at that. :-)
>
> What I propose is that we take this document (or one similar to it) and
> migrate it up to the overall Jakarta Project instead of just being a
Turbine
> policy and get all the projects to "sign" their name on it.
>
> 
>
> I think it would go a long way towards raising awareness of the need to
> deprecate things (thanks to Sam starting this with Gump) as well as make
the
> corporate types feel more comfortable with regards to depending on "that
> Open Source Software stuff"...
>
> Comments?

+1.

My only comment : you should always be allowed any API change when you
change the major revision number, without a deprecation phase (for example,
I think it's ok if version 2.0, immediately following version 1.62, has a
different API).

Remy


-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Re: [proposal] Jakarta Deprecation Policy

[Peter Donald]

At 03:38  15/5/01 -0700, Jon Stevens wrote:
>Well, there haven't been many flame wars around here recently, so let me
>start one. I seem to be good at that. :-)
>
>What I propose is that we take this document (or one similar to it) and
>migrate it up to the overall Jakarta Project instead of just being a Turbine
>policy and get all the projects to "sign" their name on it.
>
>
>
>I think it would go a long way towards raising awareness of the need to
>deprecate things (thanks to Sam starting this with Gump) as well as make the
>corporate types feel more comfortable with regards to depending on "that
>Open Source Software stuff"...
>
>Comments?

+1 for same major version non-alpha software.

I would actually go further and claim that all patch level versions MUST
under all circumstances be forward compatible. ie 1.2.3 must be compatible
with 1.2.4 and 1.2.5.

It would be in the best interest of the projects if minor versions also had
a clean migration path. ie 1.2.* -> 1.3.* could be done with minimal fuss.
(either via deprecation and compatibility layers or via update scripts/xslt
or some other method).

Across major boundaries (1.* -> 2.*) all bets are off in my mind.

Of course this is only relevent to things that are actually programmed
against. For instance it would not make sense in my mind to apply the same
policy to the James SMTPHandler as no users will program against it - but
it would make sense to apply it to james mailet API (because users program
agains it).


Cheers,

Pete

*-*
| "Faced with the choice between changing one's mind, |
| and proving that there is no need to do so - almost |
| everyone gets busy on the proof."   |
|  - John Kenneth Galbraith   |
*-*


-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Re: [proposal] Jakarta Deprecation Policy

[Daniel F. Savarese]

>What I propose is that we take this document (or one similar to it) and
>migrate it up to the overall Jakarta Project instead of just being a Turbine
>policy and get all the projects to "sign" their name on it.
>
>

+1

>Comments?

Nothing controversial in the document.  The time thing or whether removal
should coincide with minor or major version numbers (e.g., 2.1 to 2.2
instead of 2.1 to 2.1.1) should be as flexible as stated in the document
because it is both dependent on the nature of the project and its stage.
For example, projects in their early stages or in a revamping mode may 
very well be deprecating things left and right and require an accelerated
removal schedule.  Older more stable projects will probably opt for a slower
removal schedule.

daniel



-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

Re: [proposal] Jakarta Deprecation Policy

[Craig R. McClanahan]

On Tue, 15 May 2001, Jon Stevens wrote:

> Well, there haven't been many flame wars around here recently, so let me
> start one. I seem to be good at that. :-)
> 
> What I propose is that we take this document (or one similar to it) and
> migrate it up to the overall Jakarta Project instead of just being a Turbine
> policy and get all the projects to "sign" their name on it.
> 
> 
> 
> I think it would go a long way towards raising awareness of the need to
> deprecate things (thanks to Sam starting this with Gump) as well as make the
> corporate types feel more comfortable with regards to depending on "that
> Open Source Software stuff"...
> 
> Comments?
> 

I'm generally +1 with the concept of having a deprecation policy
guideline, but have some suggested clarifications:

* It would seem that a deprecation policy like this should be
  enforced only after a "version 1.0" release.  Prior to that
  time, you're still experimenting and defining architectures and
  interrelationships, so you don't really want to commit to
  anything until 1.0.

* Carrying on with that, a typical major release (2.0, 3.0, ...)
  will often be substantially different internally than the one
  before.  It seems reasonable to say that the overall compatibility
  guarantee lasts only within a "major version" series -- although
  you would not want to arbirarily change APIs at the next major
  version without a good reason.

* It's sort of implicit in your policy, but there are no guarantees
  in nightly builds -- only releases -- right?  Otherwise, you will
  risk slowing down development progress more than is necessary.

* If your definitions of product version numbers matches the typcial
  (major.minor.maintenance), I think it's way way way too fast to
  deprecate something in 2.1 and remove it in 2.1.1, no matter what
  the time interval is.  It would seem to me you would want to
  keep the deprecated calls through the next minor version (2.2 in
  the case at hand).  <>

On a more philosophical note, a deprecation policy like this can cause a
little conflict when you sit it next to the "release early release often"
mantra we like to quote.  People using this policy will want to think a
little longer than the might otherwise about what newly added features
should look like before creating a release containing them.  Once you've
done that, the toothpaste is out of the tube, and you're stuck with the
original APIs for longer than you might otherwise want to be.

> -jon
> 

Craig



-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]

[proposal] Jakarta Deprecation Policy

[Jon Stevens]

Well, there haven't been many flame wars around here recently, so let me
start one. I seem to be good at that. :-)

What I propose is that we take this document (or one similar to it) and
migrate it up to the overall Jakarta Project instead of just being a Turbine
policy and get all the projects to "sign" their name on it.



I think it would go a long way towards raising awareness of the need to
deprecate things (thanks to Sam starting this with Gump) as well as make the
corporate types feel more comfortable with regards to depending on "that
Open Source Software stuff"...

Comments?

-jon

-- 
If you come from a Perl or PHP background, JSP is a way to take
your pain to new levels. --Anonymous



-
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]