Quantcast

[ jEdit-devel ] same api for all releases in given major version

classic Classic list List threaded Threaded
17 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

[ jEdit-devel ] same api for all releases in given major version

Jarekczek
Administrator
Guys, please make this rule obvious somewhere, probably in
doc/release-procedure, to make things clear. Kazutoshi, your rules,
could you give your opinion?

And a question: does the rule also apply to prerelease version? Is it
possible to add api to "pre2"?

Here we have a merge request from Alan,
https://sourceforge.net/tracker/?func=detail&aid=3534174&group_id=588&atid=1235750.
The justification is not the strongest one, because all api changes are
always necessary and it actually does not matter how many days passed
since the release. However I would like to hear some arguments against
changing the api in pre-release, because I don't see them.

Jarek

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Alan Ezust-3
Administrator
I think in general, APIs should not "change".
But I am adding a new function that won't break any existing plugins.
I think as long as a second admin thinks it's ok, then it's ok.


On Mon, Jun 11, 2012 at 10:55 PM, Jarek Czekalski
<[hidden email]> wrote:

> Guys, please make this rule obvious somewhere, probably in
> doc/release-procedure, to make things clear. Kazutoshi, your rules,
> could you give your opinion?
>
> And a question: does the rule also apply to prerelease version? Is it
> possible to add api to "pre2"?
>
> Here we have a merge request from Alan,
> https://sourceforge.net/tracker/?func=detail&aid=3534174&group_id=588&atid=1235750.
> The justification is not the strongest one, because all api changes are
> always necessary and it actually does not matter how many days passed
> since the release. However I would like to hear some arguments against
> changing the api in pre-release, because I don't see them.
>
> Jarek
>
> ------------------------------------------------------------------------------
> Live Security Virtual Conference
> Exclusive live event will cover all the ways today's security and
> threat landscape has changed and how IT managers can respond. Discussions
> will include endpoint security, mobile security and the latest in malware
> threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
> --
> -----------------------------------------------
> jEdit Developers' List
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/jedit-devel

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Dale Anson
Administrator
I don't know that it is written down (I didn't find it in the wiki, anyway), but I think what we've discussed in the past is adding api is fine, but removing/deprecating happens only at X.0 releases.

Dale


On Tue, Jun 12, 2012 at 9:00 AM, Alan Ezust <[hidden email]> wrote:
I think in general, APIs should not "change".
But I am adding a new function that won't break any existing plugins.
I think as long as a second admin thinks it's ok, then it's ok.


On Mon, Jun 11, 2012 at 10:55 PM, Jarek Czekalski
<[hidden email]> wrote:
> Guys, please make this rule obvious somewhere, probably in
> doc/release-procedure, to make things clear. Kazutoshi, your rules,
> could you give your opinion?
>
> And a question: does the rule also apply to prerelease version? Is it
> possible to add api to "pre2"?
>
> Here we have a merge request from Alan,
> https://sourceforge.net/tracker/?func=detail&aid=3534174&group_id=588&atid=1235750.
> The justification is not the strongest one, because all api changes are
> always necessary and it actually does not matter how many days passed
> since the release. However I would like to hear some arguments against
> changing the api in pre-release, because I don't see them.
>
> Jarek
>
> ------------------------------------------------------------------------------
> Live Security Virtual Conference
> Exclusive live event will cover all the ways today's security and
> threat landscape has changed and how IT managers can respond. Discussions
> will include endpoint security, mobile security and the latest in malware
> threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
> --
> -----------------------------------------------
> jEdit Developers' List
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/jedit-devel

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel


------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Kazutoshi Satoda
Administrator
In reply to this post by Jarekczek
Jarek Czekalski wrote:
> Guys, please make this rule obvious somewhere, probably in
> doc/release-procedure, to make things clear. Kazutoshi, your rules,
> could you give your opinion?
>
> And a question: does the rule also apply to prerelease version? Is it
> possible to add api to "pre2"?

We don't have a written rule about API compatibilities for now because
there was no such clear consensus about API compatibilities at the time
release-procedure.txt was written. Then I made it up to submitter and
reviewer of merge requests. FYI, here is the relevant quote from
release-procedure.txt.
> The fix is accepted only if
>   - the fix also works for the reviewer, and
>   - the reviewer is sure that the fix doesn't include unwanted changes
> .

There was a trial to make a rule written. But it discovered that we had
some issues to define "what is API" in the first place.
http://jedit.9.n6.nabble.com/Policy-of-API-compatibility-tt1799119.html
The discussion seems stopped just because I moved my time to other
discussions at that time.

The situation of "what is API" may be better now because some
unnecessary public parts have been reduced over some minor releases till
now.

I think we will still need some API breakages at minor releases since
our APIs were still not so clean to keep compatibility. However, we
should minimize such case and I hope all new APIs will be designed
aiming this goal.

> Here we have a merge request from Alan,
> https://sourceforge.net/tracker/?func=detail&aid=3534174&group_id=588&atid=1235750.
> The justification is not the strongest one, because all api changes are
> always necessary and it actually does not matter how many days passed
> since the release. However I would like to hear some arguments against
> changing the api in pre-release, because I don't see them.

It should be clarified first why a simple call of Desktop.open() is
not enough. I couldn't find it in code itself, log message, and the
original feature request.
http://jedit.svn.sourceforge.net/jedit/?view=rev&rev=20057
http://sourceforge.net/support/tracker.php?aid=3406759

As for the general issue, I can accept such an addition of public
method if it is so small and so well designed and documented that
I can believe it doesn't cause unwanted side effects.

--
k_satoda



------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Alan Ezust-3
Administrator
Why is Desktop.open() not good on some platforms?
It is my experience that the Desktop.open() does not properly hook up
with the underlying desktop's file associations. I believe Java has
its own file associations and I always had trouble figuring out how to
set them properly.

The other techniques I have were gleaned from the launcher  and the
helperlauncher plugins.
The windows version works better than desktop.open() on  windows, the
"open" command works best on the mac,
and xdg-open works BETTER than desktop.open() in my own testing with
kde/debian/kubuntu.

Does Desktop.open() work well for anyone ?





On Tue, Jun 12, 2012 at 3:43 PM, Kazutoshi Satoda
<[hidden email]> wrote:

> Jarek Czekalski wrote:
>> Guys, please make this rule obvious somewhere, probably in
>> doc/release-procedure, to make things clear. Kazutoshi, your rules,
>> could you give your opinion?
>>
>> And a question: does the rule also apply to prerelease version? Is it
>> possible to add api to "pre2"?
>
> We don't have a written rule about API compatibilities for now because
> there was no such clear consensus about API compatibilities at the time
> release-procedure.txt was written. Then I made it up to submitter and
> reviewer of merge requests. FYI, here is the relevant quote from
> release-procedure.txt.
>> The fix is accepted only if
>>   - the fix also works for the reviewer, and
>>   - the reviewer is sure that the fix doesn't include unwanted changes
>> .
>
> There was a trial to make a rule written. But it discovered that we had
> some issues to define "what is API" in the first place.
> http://jedit.9.n6.nabble.com/Policy-of-API-compatibility-tt1799119.html
> The discussion seems stopped just because I moved my time to other
> discussions at that time.
>
> The situation of "what is API" may be better now because some
> unnecessary public parts have been reduced over some minor releases till
> now.
>
> I think we will still need some API breakages at minor releases since
> our APIs were still not so clean to keep compatibility. However, we
> should minimize such case and I hope all new APIs will be designed
> aiming this goal.
>
>> Here we have a merge request from Alan,
>> https://sourceforge.net/tracker/?func=detail&aid=3534174&group_id=588&atid=1235750.
>> The justification is not the strongest one, because all api changes are
>> always necessary and it actually does not matter how many days passed
>> since the release. However I would like to hear some arguments against
>> changing the api in pre-release, because I don't see them.
>
> It should be clarified first why a simple call of Desktop.open() is
> not enough. I couldn't find it in code itself, log message, and the
> original feature request.
> http://jedit.svn.sourceforge.net/jedit/?view=rev&rev=20057
> http://sourceforge.net/support/tracker.php?aid=3406759
>
> As for the general issue, I can accept such an addition of public
> method if it is so small and so well designed and documented that
> I can believe it doesn't cause unwanted side effects.
>
> --
> k_satoda
>
>
>
> ------------------------------------------------------------------------------
> Live Security Virtual Conference
> Exclusive live event will cover all the ways today's security and
> threat landscape has changed and how IT managers can respond. Discussions
> will include endpoint security, mobile security and the latest in malware
> threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
> --
> -----------------------------------------------
> jEdit Developers' List
> [hidden email]
> https://lists.sourceforge.net/lists/listinfo/jedit-devel

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Kazutoshi Satoda
Administrator
Alan Ezust wrote:
> The windows version works better than desktop.open() on  windows, the
> "open" command works best on the mac,
> and xdg-open works BETTER than desktop.open() in my own testing with
> kde/debian/kubuntu.

Please try describing comments in the code itself what is actually
"better", "best", and "BETTER" for each. Describing what doesn't
work maybe a good alternative way.

Also please verify the removal of "if (!f.exists())" was intended or
not with the log message not mentioning about it.


As for the merge request, please note that it is likely a bad result of
mixed changes in a revision. Things could be easier if you separate the
fix of a problem and moving the code into a new public method.

--
k_satoda



------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Alan Ezust-3
Administrator
Ok, on linux, Desktop.open() doesn't work at all.
I get an exception:
java.io.IOException: Failed to show
URI:file:/home/ezust/alan/pix/LaurenColorBar.jpg
        at sun.awt.X11.XDesktopPeer.launch(XDesktopPeer.java:93)
        at sun.awt.X11.XDesktopPeer.open(XDesktopPeer.java:61)
        at java.awt.Desktop.open(Desktop.java:272)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:616)



On Tue, Jun 12, 2012 at 6:14 PM, Kazutoshi Satoda
<[hidden email]> wrote:

> Alan Ezust wrote:
>>
>> The windows version works better than desktop.open() on  windows, the
>> "open" command works best on the mac,
>> and xdg-open works BETTER than desktop.open() in my own testing with
>> kde/debian/kubuntu.
>
>
> Please try describing comments in the code itself what is actually
> "better", "best", and "BETTER" for each. Describing what doesn't
> work maybe a good alternative way.
>
> Also please verify the removal of "if (!f.exists())" was intended or
> not with the log message not mentioning about it.
>
>
> As for the merge request, please note that it is likely a bad result of
> mixed changes in a revision. Things could be easier if you separate the
> fix of a problem and moving the code into a new public method.
>
> --
> k_satoda
>
>

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Jarekczek
Administrator
In reply to this post by Kazutoshi Satoda
W dniu 2012-06-13 00:43, Kazutoshi Satoda pisze:
> I think we will still need some API breakages at minor releases since
> our APIs were still not so clean to keep compatibility. However, we
> should minimize such case and I hope all new APIs will be designed
> aiming this goal.

I will read the sources you linked to and place a rule somewhere. Of
course if you do it before me, it would be really fine. I don't think a
definition of api must be made first. In general you all seem to agree
that new api may be added, and old api may be even broken, but that
should be avoided.

>
> It should be clarified first why a simple call of Desktop.open() is
> not enough. I couldn't find it in code itself, log message, and the
> original feature request.
> http://jedit.svn.sourceforge.net/jedit/?view=rev&rev=20057
> http://sourceforge.net/support/tracker.php?aid=3406759

Please start a separate thread because discussing "desktop.open" under
general api discussion is not a good idea. Please remember to fork
correctly:
https://sourceforge.net/apps/mediawiki/jedit/index.php?title=Conventions,_procedures#Rewriting_the_subject_.28forking.29

Jarek


------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Jarekczek
Administrator
The rule is in wiki, but I copy it here for your convenience:
https://sourceforge.net/apps/mediawiki/jedit/index.php?title=Conventions,_procedures#Merge_requests

A merge request, excluding merging into pre-release branches, should not
break api. If it is necessary to break the api, one should search for
usage of the given api in all plugins in our repositories and report it
in the request. This rule is based on following background:

  * Apache Subversion rules
    <http://subversion.apache.org/docs/community-guide/releasing.html#prerelease-caveats>

  * Policy of API compatibility - jedit-devel April 2009
    <http://jedit.9.n6.nabble.com/Policy-of-API-compatibility-tp1799119.html>

  * same api for all releases in given major version - jedit-devel June
    2012
    <http://jedit.9.n6.nabble.com/jEdit-devel-same-api-for-all-releases-in-given-major-version-tp4999180.html>


Comments?

Jarek

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Kazutoshi Satoda
Administrator
Please clarify what you are calling "major version". Our version number
M.N.P consists of Major, Minor, and Patch. So the subject sounds talking
about changes between 5.0.x and 5.1.x. But the rules you shown now about
merge requests sounds about 5.0pre1 and 5.0.0, and 5.0.1. I think we
should call the latter "releases in given minor version".

Jarek Czekalski wrote:
> A merge request, excluding merging into pre-release branches, should not
> break api.

Can it work as a rule with such a vague words "break api"?

I can't determine if the recent merge request #3534174 from Alan is
"breaking" API or not. It adds a public static method openInDesktop() in
a public class MiscUtilities. I personally won't accept an addition of a
new method or class because it is not required to make the fix. I want
encourage to separate the fix, which can go into release branches, and
the evolutions of API in trunk as it is being done for the method.

I think the rule should be more specific, to be usable as a shortcut to
reject a merge request before reviewing it in detail.

Probably we can pick some words from here with a reference:
http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs


The line seems implying a merge request for a pre-release can break API.
While the meaning of it is still in question, please explain the purpose
and rationale to put a line between pre-releases and stable releases.
Also, please clarify whether the following "If it is necessary ..."
applies to pre-releases or not.

> If it is necessary to break the api, one should search for
> usage of the given api in all plugins in our repositories and report it
> in the request.

What is the purpose of the report?

If it is meant to avoid breakages on users, please note that it is not
enough to avoid breakages of uesr local macros or plugins.


--
k_satoda



------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Jarekczek
Administrator
W dniu 06/16/2012 05:19 PM, Kazutoshi Satoda pisze:
Please clarify what you are calling "major version". Our version number
M.N.P consists of Major, Minor, and Patch. So the subject sounds talking
about changes between 5.0.x and 5.1.x. But the rules you shown now about
merge requests sounds about 5.0pre1 and 5.0.0, and 5.0.1. I think we
should call the latter "releases in given minor version".

Yes, the title is misleading. I mean't minor version.


Jarek Czekalski wrote:
A merge request, excluding merging into pre-release branches, should not
break api.

Can it work as a rule with such a vague words "break api"?

Broken api is the api which you cannot use. Adding api does not break anything. I thought it can not be understood in a different way. Can it?


I can't determine if the recent merge request #3534174 from Alan is
"breaking" API or not. It adds a public static method openInDesktop() in
a public class MiscUtilities. I personally won't accept an addition of a
new method or class because it is not required to make the fix. I want
encourage to separate the fix, which can go into release branches, and
the evolutions of API in trunk as it is being done for the method.

Dale said adding api is ok. No-one objected that. I don't see a reason to forbid it either.


I think the rule should be more specific, to be usable as a shortcut to
reject a merge request before reviewing it in detail.

Kazutoshi, please be more specific yourself. In your first post, that is linked in rules, you suggested to base on Apache Subversion. Once I did it, you post another link. I see nothing wrong in receiving critic on my rules, but it would be even better to offer also something constructive.


Probably we can pick some words from here with a reference:
http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs


You're welcome. But in general I don't think we need very complex rules. I started with a minimal set, which may be extended if it's desired.


The line seems implying a merge request for a pre-release can break API.
While the meaning of it is still in question, please explain the purpose
and rationale to put a line between pre-releases and stable releases.
Also, please clarify whether the following "If it is necessary ..."
applies to pre-releases or not.

The rule does not apply to pre-releases at all. This is taken from subversion: "Any API's (...) that appeared on trunk or in an alpha/beta/rc pre-release are not subject to any compatibility promises"


If it is necessary to break the api, one should search for
usage of the given api in all plugins in our repositories and report it
in the request.

What is the purpose of the report?

To estimate the amount of problems api breaking may bring. To discourage people from breaking api.


If it is meant to avoid breakages on users, please note that it is not
enough to avoid breakages of uesr local macros or plugins.



Jarek


------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Kazutoshi Satoda
Administrator
Jarek Czekalski wrote:
> W dniu 06/16/2012 05:19 PM, Kazutoshi Satoda pisze:
>> Please clarify what you are calling "major version". Our version number
>> M.N.P consists of Major, Minor, and Patch. So the subject sounds talking
(snip)
> Yes, the title is misleading. I mean't minor version.


>> Can it work as a rule with such a vague words "break api"?
>
> Broken api is the api which you cannot use. Adding api does not break
> anything. I thought it can not be understood in a different way. Can it?

Of course I thought that, but I wonder in what way the new rule change
the situation. An API breakage is already known as a bad thing in
general and will be rejected on merge process or at the time of the
commit in the first place.

So I was afraid that the "break api" was meant to say something
different which affects on the merge request with adds a new API.

> Dale said adding api is ok. No-one objected that. I don't see a reason
> to forbid it either.

Adding new API in a release branch means that macros or plugins which
work with X.Y.1 is not guaranteed to work with X.Y.0.

But here, on the stage of pre-release, I was wrong. I was not aware of
the line which Apache (Subversion) rule put between pre-releases and
actual X.Y.0 releases.

If we put an explicit line like that in release-procedure.txt, the
problem you are trying to solve can be solved. Right?


--
k_satoda



------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Dale Anson
Administrator
In reply to this post by Jarekczek
This seems to me to be a pretty simple thing -- breaking API means removing existing API. In general, the rule should be to not do it. If a specific API method is bad, for example, it's known to cause a memory leak or other undesirable behavior, then it should be deprecated and an explanation added for at least the duration of the current major release and might be a candidate for removal in the next major release. Sun's policy for Java was to deprecate but never remove existing API to avoid breaking older applications. In our case, those older applications are plugins that still work, but would break with removing certain methods.

Adding API breaks nothing -- no one is using it except perhaps he who added it, so I see no problem with allowing such additions at any time.

Dale


On Sat, Jun 16, 2012 at 2:15 PM, Jarek Czekalski <[hidden email]> wrote:
W dniu 06/16/2012 05:19 PM, Kazutoshi Satoda pisze:
Please clarify what you are calling "major version". Our version number
M.N.P consists of Major, Minor, and Patch. So the subject sounds talking
about changes between 5.0.x and 5.1.x. But the rules you shown now about
merge requests sounds about 5.0pre1 and 5.0.0, and 5.0.1. I think we
should call the latter "releases in given minor version".

Yes, the title is misleading. I mean't minor version.



Jarek Czekalski wrote:
A merge request, excluding merging into pre-release branches, should not
break api.

Can it work as a rule with such a vague words "break api"?

Broken api is the api which you cannot use. Adding api does not break anything. I thought it can not be understood in a different way. Can it?



I can't determine if the recent merge request #3534174 from Alan is
"breaking" API or not. It adds a public static method openInDesktop() in
a public class MiscUtilities. I personally won't accept an addition of a
new method or class because it is not required to make the fix. I want
encourage to separate the fix, which can go into release branches, and
the evolutions of API in trunk as it is being done for the method.

Dale said adding api is ok. No-one objected that. I don't see a reason to forbid it either.



I think the rule should be more specific, to be usable as a shortcut to
reject a merge request before reviewing it in detail.

Kazutoshi, please be more specific yourself. In your first post, that is linked in rules, you suggested to base on Apache Subversion. Once I did it, you post another link. I see nothing wrong in receiving critic on my rules, but it would be even better to offer also something constructive.


Probably we can pick some words from here with a reference:
http://wiki.eclipse.org/index.php/Evolving_Java-based_APIs


You're welcome. But in general I don't think we need very complex rules. I started with a minimal set, which may be extended if it's desired.



The line seems implying a merge request for a pre-release can break API.
While the meaning of it is still in question, please explain the purpose
and rationale to put a line between pre-releases and stable releases.
Also, please clarify whether the following "If it is necessary ..."
applies to pre-releases or not.

The rule does not apply to pre-releases at all. This is taken from subversion: "Any API's (...) that appeared on trunk or in an alpha/beta/rc pre-release are not subject to any compatibility promises"



If it is necessary to break the api, one should search for
usage of the given api in all plugins in our repositories and report it
in the request.

What is the purpose of the report?

To estimate the amount of problems api breaking may bring. To discourage people from breaking api.



If it is meant to avoid breakages on users, please note that it is not
enough to avoid breakages of uesr local macros or plugins.



Jarek


------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel



------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Jarekczek
Administrator
In reply to this post by Kazutoshi Satoda
W dniu 06/17/2012 06:51 AM, Kazutoshi Satoda pisze:
> Jarek Czekalski wrote:
>
>>
>> Broken api is the api which you cannot use. Adding api does not break
>> anything. I thought it can not be understood in a different way. Can it?
>
> Of course I thought that, but I wonder in what way the new rule change
> the situation.

In such a way thay you will not object adding new api.

> Adding new API in a release branch means that macros or plugins which
> work with X.Y.1 is not guaranteed to work with X.Y.0.

What's wrong with it? The plugin specifies its minimal requirements.

>
> (...)
>
> If we put an explicit line like that in release-procedure.txt, the
> problem you are trying to solve can be solved. Right?

Putting the rule in 2 places is unnecessary. Is Wiki not enough?

Jarek

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Kazutoshi Satoda
Administrator
Jarek Czekalski wrote:
> W dniu 06/17/2012 06:51 AM, Kazutoshi Satoda pisze:
>> Jarek Czekalski wrote:
>>> Broken api is the api which you cannot use. Adding api does not break
>>> anything. I thought it can not be understood in a different way. Can it?
>>
>> Of course I thought that, but I wonder in what way the new rule change
>> the situation.
>
> In such a way thay you will not object adding new api.

I think adding new API should be objected if the rationale, semantics,
or naming etc... are questionable. Accepting such addition may become
unreasonable burden in the future to keep the compatibility of them.

I'm afraid that the new rule can be used to discourage such objections.

>> Adding new API in a release branch means that macros or plugins which
>> work with X.Y.1 is not guaranteed to work with X.Y.0.
>
> What's wrong with it? The plugin specifies its minimal requirements.

As far as I know, minimal requirements have had always 0 in its patch
version, and a plugin release submission is verified with a most recent
patch version.

By accepting new API in a release branch, this will become vulnerable.
For example, a plugin which has X.Y.0 as its minimal requirement can be
released since it works with X.Y.1, but it is not guaranteed to work on
X.Y.0 in fact.

This may be fixed by requiring submitters to set a correct patch
version, but it can be additional burden on both submitters and release
managers. If the current process already require this, my worry only
applies to macros or plugins shared in the wild.


>> If we put an explicit line like that in release-procedure.txt, the
>> problem you are trying to solve can be solved. Right?
>
> Putting the rule in 2 places is unnecessary. Is Wiki not enough?

Since the new rule seems to be tightly coupled with existing rule in
release-procedure.txt, I though it's better to put the rule in one
place together.

Now I think it may be better to put all of the text into a Wiki page.
It is more suitable to have sections, lists, and links. Can we agree
on it? Would you please translate it to Wiki, or shall I?

--
k_satoda



------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Jarekczek
Administrator
W dniu 06/17/2012 11:05 AM, Kazutoshi Satoda pisze:

> Jarek Czekalski wrote:
>> W dniu 06/17/2012 06:51 AM, Kazutoshi Satoda pisze:
>>> Jarek Czekalski wrote:
>>>> Broken api is the api which you cannot use. Adding api does not break
>>>> anything. I thought it can not be understood in a different way.
>>>> Can it?
>>>
>>> Of course I thought that, but I wonder in what way the new rule change
>>> the situation.
>>
>> In such a way thay you will not object adding new api.
>
> I think adding new API should be objected if the rationale, semantics,
> or naming etc... are questionable. Accepting such addition may become
> unreasonable burden in the future to keep the compatibility of them.
>
Kazutoshi, is this a suggestion for a new rule: "adding new API should
be objected if the rationale, semantics,
or naming etc... are questionable" ? If not, could you try to convert it
to something that we could add as a rule, or at least discuss it?

Jarek

------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: [ jEdit-devel ] same api for all releases in given major version

Kazutoshi Satoda
Administrator
Jarek Czekalski wrote:
> W dniu 06/17/2012 11:05 AM, Kazutoshi Satoda pisze:
>> I think adding new API should be objected if the rationale, semantics,
>> or naming etc... are questionable. Accepting such addition may become
>> unreasonable burden in the future to keep the compatibility of them.
>>
> Kazutoshi, is this a suggestion for a new rule: "adding new API should
> be objected if the rationale, semantics,
> or naming etc... are questionable" ? If not, could you try to convert it
> to something that we could add as a rule, or at least discuss it?

I won't set such a rule. Objection on any change should be done freely
if there is a reason. Setting a white list can be seen implying the
opposite.

Do you still want to discourage objections? What is a good to do so?

Please note that the current rule of merge process allows to accept such
a change under some objections if two persons anyway agree to merge it.

--
k_satoda



------------------------------------------------------------------------------
Live Security Virtual Conference
Exclusive live event will cover all the ways today's security and
threat landscape has changed and how IT managers can respond. Discussions
will include endpoint security, mobile security and the latest in malware
threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/
--
-----------------------------------------------
jEdit Developers' List
[hidden email]
https://lists.sourceforge.net/lists/listinfo/jedit-devel
Loading...