Strings - deprecated functions

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
48 messages Options
123
Reply | Threaded
Open this post in threaded view
|

Re: Strings - deprecated functions

Fred Hebert-2
On 11/27, Robert Virding wrote:

>I think it is perfectly possible to keep the old functions in the same
>'string' module in a clean way if you just reorganise the documentation.
>Now all the functions, both the new and the obsolete, are kept in one
>alphabetical list which makes it difficult to see which are which and get a
>clear overview of the functions. Why not just separate the functions into 2
>groups, the new and the obsolete, each in its own alphabetical list? This
>would make it easy to keep the old functions while making it easy for
>people to choose the newer ones, and migrate code if desired. There would
>then be no need to get rid of the old functions and break backward
>compatibility.
>

The index on the left of the docs is alphabetical (that's automated),
but the functions on the page itself are already in a new/old set of
functions, each sorted alphabetically.
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Strings - deprecated functions

Richard A. O'Keefe-2
In reply to this post by Robert Virding
An alphabetic list has two uses:
 1. find a function with (approximately) known semantics
    but unknown name
 2. find the documentation for a known name.

Splitting the documentation into two lists hurts 2 without
actually helping 1.

A more informative approach would be to have a line
added: 12.3 deprecated: 20.3 to be removed: 24.0
perhaps with dates, and it should be possible to generate at
least the 'added:' and 'deprecated:' parts automatically.

"added" = JavaDoc "since".  Compare also the macOS X
__OSX_AVAILABLE_STARTING(<macos vsn>, <ios vsn>)
__OSX_AVAILABLE_BUT_DEPRECATED(<macos in vsn>, <macos out vsn>,
    <ios in vsn>, <ios out vsn>)


_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Strings - deprecated functions

bengt e
In reply to this post by Robert Virding
Greetings,

It would be nice if Erlang modules where prefixed with their app. The new functions would then be in stdlib_strings, instead of string. I know that this would only help once, ie when functions in stdlib_strings are deprecated we would have the current problem again. But that would be in 20 years time, right? Perhaps a better idea has come up by then.


bengt

On Mon, Nov 27, 2017 at 3:03 AM, Robert Virding <[hidden email]> wrote:
I think it is perfectly possible to keep the old functions in the same 'string' module in a clean way if you just reorganise the documentation. Now all the functions, both the new and the obsolete, are kept in one alphabetical list which makes it difficult to see which are which and get a clear overview of the functions. Why not just separate the functions into 2 groups, the new and the obsolete, each in its own alphabetical list? This would make it easy to keep the old functions while making it easy for people to choose the newer ones, and migrate code if desired. There would then be no need to get rid of the old functions and break backward compatibility.

Robert


On 25 November 2017 at 15:10, Jesper Louis Andersen <[hidden email]> wrote:
I think the only way to approach a problem like this is by asking:

"How much are you willing to spend on your backwards compatibility?"

Maintaining a long-term-release of a piece of software is no easy feat. It requires effort, and that requires money. If you need stability from an older release and you need control of that release, you have to give the right people some money.

In Solaris, Sun had the advantage that they could use the Zone construction in the OS. You could brand a zone, such that inside the zone, the Solaris (10) system operates as if it were a Solaris 8 or 9 system. This is achieved by manipulating the syscall table of the kernel and handling some syscalls differently. Maintenance of such a compat layer is time-consuming, however. In FreeBSD, you have libcompat for much the same thing: It provides you with a way to run legacy binaries on a new system for a while, so you don't have to upgrade all of your software in one go.

In Android development, the system runs by "API levels" (corresponding somewhat to Erlang/OTP major releases). A given library functionality is *introduced* at some API level, *deprecated* at a higher level and eventually *removed* in an even higher API level. This means that any function is alive over a "window" from introduction to removal.

In practice, one has to cope with changes of a system over time. What is a problem is the rate-of-change, not the change itself. Historically, Erlang is a fairly slow-changing system I think. My older Haskell code rarely compiles, and the recent changes in OCaml also requires far more interaction to make things work again on some code bases.

The changes are likely to require library maintainers to handle several releases and this is where the hard part of the work is. A single project can target a single Erlang release. A library, which may have to span several Erlang releases

* Cannot use a new function when it is introduced. That would break backwards compatibility.
* Cannot use functions which have been removed. That would break forwards compatibility.

How large a deprecation window can be depends largely on factors such as "how common is the function, and how easy is it to change the code?", "Do we have a sponsor who wishes the older versions kept around, paying us to do so?", and so on. You may quickly find it is cheaper for you to upgrade the Erlang/OTP release rather than maintaining and older version of it.



On Sat, Nov 25, 2017 at 2:50 AM <[hidden email]> wrote:
A couple of years ago I was working through a Java book.
Not one of the examples got a clean compile.  Not one.
oddly enough, it was string-handling functions that had
been deprecated, and oddly enough, in my environment the
old functions still did everything I needed.

It's not just Erlang and Java.  I had C code using some of
the classic string functions in ways I had carefully ensured
were correct.  Porting to the next version of the Unix
flavour I was using, the linker screamed at me about unsafe
functions.  Since I wanted other people to use the program
and didn't want them looking down on me, I spent a merry
couple of hours changing the code to use memcpy instead of
strcpy and so on.

Again, I have a program which works fine in Solaris 10, Open
Solaris, and Solaris 11 Express.  It uses a mix of old
functions (hey, if the code still works, why change it, am I
right?) and new functions (if you can call POSIX 2008 "new".)
But OpenIndiana?  I am still baffled as to what combination of
feature test macros I can set to make the program compile, and
am coming to the conclusion that there isn't one.

Did I mention the trouble I've been having with Ubuntu 17.10?
I'll spare you that, but let's just say that putting standard
headers in nonstandard places really really does not help.

I don't really have a solution.  It seems as though the only
thing you can do to ensure that old code continues to work is
to keep a VM imagine with a complete copy of the environment
it used to work in.

Good luck plugging new libraries into that, though.



_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions



_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions



_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Strings - deprecated functions

Anthony Ramine-4
In reply to this post by Robert Virding
I don't particularly care about the old functions myself (if you want to run old code, just run a damn old VM, problem solved), but a way to reorganise the documentation to accommodate for that would also bring closure to  https://github.com/erlang/otp/pull/363, which would be nice.

> Le 27 nov. 2017 à 03:03, Robert Virding <[hidden email]> a écrit :
>
> I think it is perfectly possible to keep the old functions in the same 'string' module in a clean way if you just reorganise the documentation. Now all the functions, both the new and the obsolete, are kept in one alphabetical list which makes it difficult to see which are which and get a clear overview of the functions. Why not just separate the functions into 2 groups, the new and the obsolete, each in its own alphabetical list? This would make it easy to keep the old functions while making it easy for people to choose the newer ones, and migrate code if desired. There would then be no need to get rid of the old functions and break backward compatibility.

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Strings - deprecated functions

Loïc Hoguin-3
The reason this PR was closed is a little ridiculous.

stdlib has erl_internal and other modules before most modules that are
useful to most people and the important modules are effectively hidden
in this confusing mess of useful and not-so-useful-at-all modules.

Meanwhile the compiler application has exactly one module right now;
you're not going to confuse anyone by adding a couple more modules.

Ridiculous.

On 11/27/2017 06:01 PM, Anthony Ramine wrote:

> I don't particularly care about the old functions myself (if you want to run old code, just run a damn old VM, problem solved), but a way to reorganise the documentation to accommodate for that would also bring closure to  https://github.com/erlang/otp/pull/363, which would be nice.
>
>> Le 27 nov. 2017 à 03:03, Robert Virding <[hidden email]> a écrit :
>>
>> I think it is perfectly possible to keep the old functions in the same 'string' module in a clean way if you just reorganise the documentation. Now all the functions, both the new and the obsolete, are kept in one alphabetical list which makes it difficult to see which are which and get a clear overview of the functions. Why not just separate the functions into 2 groups, the new and the obsolete, each in its own alphabetical list? This would make it easy to keep the old functions while making it easy for people to choose the newer ones, and migrate code if desired. There would then be no need to get rid of the old functions and break backward compatibility.
>
> _______________________________________________
> erlang-questions mailing list
> [hidden email]
> http://erlang.org/mailman/listinfo/erlang-questions
>

--
Loïc Hoguin
https://ninenines.eu
_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Strings - deprecated functions

Lloyd R. Prentice-2
Hello,

+1 re: the ordering of modules and functions in stdlib.

I'm fine with alphabetical ordering. But I do feel that complementary schemes are worth consideration.

 So here's a challenge:

Suppose we have a parallel ordering of modules and functions within modules by frequency of use in the wild.

Shouldn't be too hard to generate with a few well-chosen NLP tools.

I'd do it myself if I could spare a Saturday morning. But I can't.

So I'll offer a bounty--- a $100.00 USD Amazon gift card to first person who generates such a list based on a statistical representative sample of all Erlang source code posted on GitHub within the next month.

All the best,

LRP


> On Nov 27, 2017, at 4:22 PM, Loïc Hoguin <[hidden email]> wrote:
>
> The reason this PR was closed is a little ridiculous.
>
> stdlib has erl_internal and other modules before most modules that are useful to most people and the important modules are effectively hidden in this confusing mess of useful and not-so-useful-at-all modules.
>
> Meanwhile the compiler application has exactly one module right now; you're not going to confuse anyone by adding a couple more modules.
>
> Ridiculous.
>
>> On 11/27/2017 06:01 PM, Anthony Ramine wrote:
>> I don't particularly care about the old functions myself (if you want to run old code, just run a damn old VM, problem solved), but a way to reorganise the documentation to accommodate for that would also bring closure to  https://github.com/erlang/otp/pull/363, which would be nice.
>>> Le 27 nov. 2017 à 03:03, Robert Virding <[hidden email]> a écrit :
>>>
>>> I think it is perfectly possible to keep the old functions in the same 'string' module in a clean way if you just reorganise the documentation. Now all the functions, both the new and the obsolete, are kept in one alphabetical list which makes it difficult to see which are which and get a clear overview of the functions. Why not just separate the functions into 2 groups, the new and the obsolete, each in its own alphabetical list? This would make it easy to keep the old functions while making it easy for people to choose the newer ones, and migrate code if desired. There would then be no need to get rid of the old functions and break backward compatibility.
>> _______________________________________________
>> erlang-questions mailing list
>> [hidden email]
>> http://erlang.org/mailman/listinfo/erlang-questions
>
> --
> Loïc Hoguin
> https://ninenines.eu
> _______________________________________________
> erlang-questions mailing list
> [hidden email]
> http://erlang.org/mailman/listinfo/erlang-questions

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Strings - deprecated functions

PAILLEAU Eric
In reply to this post by Richard A. O'Keefe-2
+1

Erlang release version of first introduction would be as well very
usefull for people wanting to let their code compatible with some releases.
Edoc tag  @since  exists...

Another annoying thing I think is that documentation does not help to
write your code quickly :

in documentation you got for instance for maps module :

find(Key, Map) -> {ok, Value} | error

I offen copy and paste possible return values for a 'case' and have to
rewrite all. As well module name is missing, having to always think to
add it.

Would be very nice to have a prepared case statement with all possible
return value in clipboard when clicking on function.
case maps:find(Key, Map) of
        {ok, Value} ->  ;
         error       ->
end


Le 27/11/2017 à 08:06, [hidden email] a écrit :

> An alphabetic list has two uses:
>   1. find a function with (approximately) known semantics
>      but unknown name
>   2. find the documentation for a known name.
>
> Splitting the documentation into two lists hurts 2 without
> actually helping 1.
>
> A more informative approach would be to have a line
> added: 12.3 deprecated: 20.3 to be removed: 24.0
> perhaps with dates, and it should be possible to generate at
> least the 'added:' and 'deprecated:' parts automatically.
>
> "added" = JavaDoc "since".  Compare also the macOS X
> __OSX_AVAILABLE_STARTING(<macos vsn>, <ios vsn>)
> __OSX_AVAILABLE_BUT_DEPRECATED(<macos in vsn>, <macos out vsn>,
>      <ios in vsn>, <ios out vsn>)
>
>
> _______________________________________________
> erlang-questions mailing list
> [hidden email]
> http://erlang.org/mailman/listinfo/erlang-questions
>

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
Reply | Threaded
Open this post in threaded view
|

Re: Strings - deprecated functions

Pierre Fenoll-2
ter+1 on that clipboard idea!
I really need to get to work on https://github.com/erldocs/erldocs_other
and to incorporate your https://github.com/crownedgrouse/geas project Eric!

I have been spending some time in golang doc pages... they have examples as well as links to source code. Erldocs.com should be more like that. I don’t have a bounty to suggest but I’ll review pull requests. 

WRT doing some ML on the corpus of open source Erlang projects:
the other.erldocs.com project aims to aggregate the data & to help anyone process it for the greater good.
It just needs finishing...

On Sat 2 Dec 2017 at 11:36, PAILLEAU Eric <[hidden email]> wrote:
+1

Erlang release version of first introduction would be as well very
usefull for people wanting to let their code compatible with some releases.
Edoc tag  @since  exists...

Another annoying thing I think is that documentation does not help to
write your code quickly :

in documentation you got for instance for maps module :

find(Key, Map) -> {ok, Value} | error

I offen copy and paste possible return values for a 'case' and have to
rewrite all. As well module name is missing, having to always think to
add it.

Would be very nice to have a prepared case statement with all possible
return value in clipboard when clicking on function.
case maps:find(Key, Map) of
        {ok, Value} ->  ;
         error       ->
end


Le 27/11/2017 à 08:06, [hidden email] a écrit :
> An alphabetic list has two uses:
>   1. find a function with (approximately) known semantics
>      but unknown name
>   2. find the documentation for a known name.
>
> Splitting the documentation into two lists hurts 2 without
> actually helping 1.
>
> A more informative approach would be to have a line
> added: 12.3 deprecated: 20.3 to be removed: 24.0
> perhaps with dates, and it should be possible to generate at
> least the 'added:' and 'deprecated:' parts automatically.
>
> "added" = JavaDoc "since".  Compare also the macOS X
> __OSX_AVAILABLE_STARTING(<macos vsn>, <ios vsn>)
> __OSX_AVAILABLE_BUT_DEPRECATED(<macos in vsn>, <macos out vsn>,
>      <ios in vsn>, <ios out vsn>)
>
>
> _______________________________________________
> erlang-questions mailing list
> [hidden email]
> http://erlang.org/mailman/listinfo/erlang-questions
>

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions

_______________________________________________
erlang-questions mailing list
[hidden email]
http://erlang.org/mailman/listinfo/erlang-questions
123