[ANN] lsocket - Another library for sockets in lua

classic Classic list List threaded Threaded
38 messages Options
12
Reply | Threaded
Open this post in threaded view
|

[ANN] lsocket - Another library for sockets in lua

liam mail


On Wednesday, 27 March 2013, Roberto Ierusalimschy <[hidden email]> wrote:
>> > Innovation is great, but it's also worth concentrating some effort on
>> > the standard libs.
>>
>> Lua has a networking library as part of the core or at least blessed ? When
>> did this happen ?
>
> I guess LuaSocket has been blessed by the community a long time ago.
>
> -- Roberto
>
>

I would not disagree that a Lua community of a few thousand did bless it for the Million odd users, although as Steve since points out that does not make it standard.

--Liam
Reply | Threaded
Open this post in threaded view
|

Re: [ANN] lsocket - Another library for sockets in lua

steve donovan
On Wed, Mar 27, 2013 at 2:19 PM, liam mail <[hidden email]> wrote:
> I would not disagree that a Lua community of a few thousand did bless it for
> the Million odd users, although as Steve since points out that does not make
> it standard.

Although he would like to call it a de-facto standard ;)

Reply | Threaded
Open this post in threaded view
|

Re: [ANN] lsocket - Another library for sockets in lua

William Ahern
In reply to this post by Gunnar Zötl
On Wed, Mar 27, 2013 at 09:40:46AM +0100, "Gunnar Zötl" wrote:

> Hi,
>
> this message is to announce the availability of lsocket, another take of a
> socket programming library for lua.
>
> It is not intended to be a complete socket api, but easy to use and good enough
> for most tasks. Both IPv4 and IPv6 are supported, as are tcp and udp, and also
> IPv4 broadcasts and IPv6 multicasts.
>
> With lsocket, I restrict myself to what I percieve as the most common use cases
> of socket programming, and attempting to make those things
> easy. Also, everything (apart from select, and, if you wish to count them, dns
> resolutions) is non-blocking.

IMO, a sockets library cannot be non-blocking if the DNS is blocking.
Queries can often take several seconds to complete, or in some cases, never.
If you're concurrently servicing 100 or 1000 open connections (or more!),
blocking on DNS for 5 seconds, or just .5 seconds, is an absolute
non-starter. I work at a networking appliance and "cloud" company, and this
happens _all_ _the_ _time_, and almost invariably if the names aren't
cached. Out-of-bailwick SOAs are the norm, and they dramatically increase
resolution time.

I don't have the time to fix the Win32 build (it worked once-upon-a-time),
but you can try with this library:

        http://25thandclement.com/~william/projects/dns.c.html

It's a fully non-blocking DNS library, *without* any callbacks, so it's
rather trivial to integrate into Lua (as I did w/ my cqueues library).

The Enlightenment networking subsystem maintainer would be thrilled if you
actually patched it up to work on Windows again. (Windows isn't officially
supported by Enlightenment, but Nokia would prefer the toolkit be portable
to embedded Windows systems). The big ticket item needed for proper Windows
support is reading the current nameservers (when in non-recursive mode).
There are 3 or 4 different techniques floating around (using 2 or 3
different Windows APIs), and I haven't had the time to determine which is
the best or most appropriate.


Reply | Threaded
Open this post in threaded view
|

Re: [ANN] lsocket - Another library for sockets in lua

Sean Conner
It was thus said that the Great William Ahern once stated:

>
> IMO, a sockets library cannot be non-blocking if the DNS is blocking.
> Queries can often take several seconds to complete, or in some cases, never.
> If you're concurrently servicing 100 or 1000 open connections (or more!),
> blocking on DNS for 5 seconds, or just .5 seconds, is an absolute
> non-starter. I work at a networking appliance and "cloud" company, and this
> happens _all_ _the_ _time_, and almost invariably if the names aren't
> cached. Out-of-bailwick SOAs are the norm, and they dramatically increase
> resolution time.
>
> I don't have the time to fix the Win32 build (it worked once-upon-a-time),
> but you can try with this library:
>
> http://25thandclement.com/~william/projects/dns.c.html

  Another DNS library is SPCDNS [1].  It's primary purpose is to encode and
decode DNS packets, which makes it rather easy to integrate into a project
with an existing network API instead of it (poorly) handling the network
activity.  And it comes with Lua bindings.

  -spc

[1] https://github.com/spc476/SPCDNS

Reply | Threaded
Open this post in threaded view
|

Re: [ANN] lsocket - Another library for sockets in lua

William Ahern
On Wed, Mar 27, 2013 at 06:23:41PM -0400, Sean Conner wrote:

> It was thus said that the Great William Ahern once stated:
> >
> > IMO, a sockets library cannot be non-blocking if the DNS is blocking.
> > Queries can often take several seconds to complete, or in some cases, never.
> > If you're concurrently servicing 100 or 1000 open connections (or more!),
> > blocking on DNS for 5 seconds, or just .5 seconds, is an absolute
> > non-starter. I work at a networking appliance and "cloud" company, and this
> > happens _all_ _the_ _time_, and almost invariably if the names aren't
> > cached. Out-of-bailwick SOAs are the norm, and they dramatically increase
> > resolution time.
> >
> > I don't have the time to fix the Win32 build (it worked once-upon-a-time),
> > but you can try with this library:
> >
> > http://25thandclement.com/~william/projects/dns.c.html
>
>   Another DNS library is SPCDNS [1].

Nice.

> It's primary purpose is to encode and decode DNS packets, which makes it
> rather easy to integrate into a project with an existing network API
> instead of it (poorly) handling the network activity. And it comes with
> Lua bindings.
>

Are you implying that my library does network I/O poorly? ;)

Reply | Threaded
Open this post in threaded view
|

Re: Checking for rocks up

Hisham
In reply to this post by Laurent FAILLIE
On 27 March 2013 09:01, Laurent Faillie <[hidden email]> wrote:
> I second also the suggestion to add something in luarocks for automatic
> checking.
> It's easier for users and wide spread in all packages management system.

Checking for available updates shouldn't be hard (as others mentioned
already), so yes, it would be a nice feature for LuaRocks.

However, I am wary of coding a more automagic command such as
`luarocks update-all` because it would be very unlikely that it would
do 'the right thing' all the time:

* Rock X has a new version 2.0, which is incompatible with previous
version 1.5. Rock Y depended on rock X, but it didn't specify a
version (or it was optimistic and asked for "X >= 1.0"). Rock Y
doesn't have an updated version yet which is compatible with X 2.0.
Now rock Y is broken.
* Even with the fact that LuaRocks can keep multiple versions in the
repository, one can only make use of that if the dependencies
information is correct (see above example) and when the
luarocks.loader package loader is used. Nowadays the normal use of
LuaRocks is without the custom loader, so most users could be affected
by situations like that.
* Users may have their own scripts which are not in LuaRocks, but
which use modules installed by LuaRocks. The same dependency issues
apply, and there is no explicit information about which version of X
the user's script wants. Cue "my script was working before `luarocks
update-all`, now it's broken".

`luarocks available-updates`, which shows newer versions of installed
rocks, so that the user can request installation of whatever they
want, is a much safer approach. How does that sound?

-- Hisham
http://hisham.hm/

Reply | Threaded
Open this post in threaded view
|

Re: Checking for rocks up

Laurent FAILLIE
Le 28/03/2013 01:07, Hisham a écrit :

> On 27 March 2013 09:01, Laurent Faillie <[hidden email]> wrote:
>> I second also the suggestion to add something in luarocks for automatic
>> checking.
>> It's easier for users and wide spread in all packages management system.
> Checking for available updates shouldn't be hard (as others mentioned
> already), so yes, it would be a nice feature for LuaRocks.
>
> However, I am wary of coding a more automagic command such as
> `luarocks update-all` because it would be very unlikely that it would
> do 'the right thing' all the time:
I totally agree : updates must be done manually under user's
responsibility (even with package management system with strong QA
policy as Gentoo's portage - probably the best one -, you may have bad
surprises).

But having a simple tool to highlight potential updates will help. Even
if home made script can be easy made (thanks for all who replied), I
think its best place is part of LuaRocks :)

Bye

Laurent

Reply | Threaded
Open this post in threaded view
|

Re: [ANN] lsocket - Another library for sockets in lua

Sean Conner
In reply to this post by William Ahern
It was thus said that the Great William Ahern once stated:

> On Wed, Mar 27, 2013 at 06:23:41PM -0400, Sean Conner wrote:
> > It was thus said that the Great William Ahern once stated:
> > >
> > > IMO, a sockets library cannot be non-blocking if the DNS is blocking.
> > > Queries can often take several seconds to complete, or in some cases, never.
> > > If you're concurrently servicing 100 or 1000 open connections (or more!),
> > > blocking on DNS for 5 seconds, or just .5 seconds, is an absolute
> > > non-starter. I work at a networking appliance and "cloud" company, and this
> > > happens _all_ _the_ _time_, and almost invariably if the names aren't
> > > cached. Out-of-bailwick SOAs are the norm, and they dramatically increase
> > > resolution time.
> > >
> > > I don't have the time to fix the Win32 build (it worked once-upon-a-time),
> > > but you can try with this library:
> > >
> > > http://25thandclement.com/~william/projects/dns.c.html
> >
> >   Another DNS library is SPCDNS [1].
>
> Nice.
>
> > It's primary purpose is to encode and decode DNS packets, which makes it
> > rather easy to integrate into a project with an existing network API
> > instead of it (poorly) handling the network activity. And it comes with
> > Lua bindings.
> >
>
> Are you implying that my library does network I/O poorly? ;)

  Well ...

  True story.  At work, two developers (on two different projects) were both
trying to use an existing DNS resolving library (c-ares).  Both were having
major difficulty in getting it to work and it all came down to the network
code in the library.  Not only was it trying to do too much, but it didn't
mesh well with the existing network stack in the application.  

  I'm sure that c-ares would be fine for an application that wasn't so
network heavy as both projects (both in telephony [2]).  But with SPCDNS,
since it doesn't really handle the network portion of DNS, was much easier
to integrate into the projects (literally within a couple of days) since
they could integrate the DNS calls with the rest of the network stack in
place.

  What I've noticed (having looked at most of the existing DNS resolving
libraries) is that they tend to skimp on decoding DNS records (leaving most
of that up to the application) and go to extreme lengths in handling the
network side of the protocol.  SPCDNS took the opposite approach---handing
the DNS decoding [3] and leaving the network side to the application.

  -spc (There's something to be said about separating encoding/decoding and
        transports in protocols ... )

[1] Footnote from a previous message

[2] Telephony uses DNS for caller ID information.  

[3] It handles 32 DNS record types---about 26 more types than other DNS
        resolving libraries.

Reply | Threaded
Open this post in threaded view
|

Re: [ANN] lsocket - Another library for sockets in lua

William Ahern
On Wed, Mar 27, 2013 at 09:08:41PM -0400, Sean Conner wrote:
<snip>
>   True story.  At work, two developers (on two different projects) were both
> trying to use an existing DNS resolving library (c-ares).  Both were having
> major difficulty in getting it to work and it all came down to the network
> code in the library.  Not only was it trying to do too much, but it didn't
> mesh well with the existing network stack in the application.  

That was my story, too. Callbacks are just not composable. The operating
system guys figured this out in the 70s. GUI writers are still playing catch
up, with Lua developers leading the way!

It doesn't help, though, that Microsoft still pushes hardware-asynchronous
callbacks. There's a reason why they made SSL a kernel service; it's a
nightmare to stitch it into the execution path in userland, w/ umpteen
levels of callbacks. Same reason why integrating ADNS or c-ares into complex
network stacks is so difficult.

>   I'm sure that c-ares would be fine for an application that wasn't so
> network heavy as both projects (both in telephony [2]).  But with SPCDNS,
> since it doesn't really handle the network portion of DNS, was much easier
> to integrate into the projects (literally within a couple of days) since
> they could integrate the DNS calls with the rest of the network stack in
> place.

Copy that. I write _all_ of my libraries to be non-blocking, restartable
state machines. DNS, HTTP, RTSP, SMTP, even MIME. I write them as push-pull
parsers. Basically, a method to _push_ data into the machine, and then a
method to _pull_ out the enqueued tokens/events. This makes them
immeasurably easier to integrate into applications. And you can easily layer
all kinds of I/O patterns atop this, including tiny auxiliary wrappers which
handle socket I/O.**

When I began writing dns.c, this is how I wanted to do it--no instrinsic
socket support whatsoever. Aside from providing all the packet and record
code as a resuseable API, I wanted to be able instantiate a resolver
instance which consumed and emitted operations to be performed by the
caller. But this simply proved too unwieldly. The socket operations were
simply too complex (complex timeouts, multiple exchanges with multiple
peers), and I figured I might as well put it all in one place rather than
recreate it in every application.

But I can totally appreciate electing to go in the other direction, slimming
the library down rather than beefing it up.

>   What I've noticed (having looked at most of the existing DNS resolving
> libraries) is that they tend to skimp on decoding DNS records (leaving most
> of that up to the application) and go to extreme lengths in handling the
> network side of the protocol.  SPCDNS took the opposite approach---handing
> the DNS decoding [3] and leaving the network side to the application.

I can't dispute your analysis. We all prefer different tradeoffs.
 
<snip>
> [3] It handles 32 DNS record types---about 26 more types than other DNS
> resolving libraries.

I can't find any code which handles NAPTR pattern matching in SPCDNS. Do you
just use the POSIX regex library in your applications? (Presuming you
actually use NAPTR records.) I was always afraid to execute regular
expressions from untrusted third-parties, _especially_ with builtin POSIX
regex engines, which are mostly pretty horrible.


** I cringe most of the time when I hear people discussing code abstraction
and modularity. Beyond basic encapsulation, people abstract the wrong stuff.
They usually spend no time whatsoever thinking about how to support
different concurrency, parallelism, or code flow patterns, and instead
obsess over useless OOP abstractions. I can _easily_ fix poor object or
encapsulation abstractions by hacking the code. It's usually impossible to
address a poor approach to execution flow or data management.

So, I totally understand your approach to SPCDNS.

Reply | Threaded
Open this post in threaded view
|

Re: [ANN] lsocket - Another library for sockets in lua

Hadriel Kaplan

On Mar 28, 2013, at 12:36 AM, William Ahern <[hidden email]> wrote:

>> [3] It handles 32 DNS record types---about 26 more types than other DNS
>> resolving libraries.
>
> I can't find any code which handles NAPTR pattern matching in SPCDNS. Do you
> just use the POSIX regex library in your applications? (Presuming you
> actually use NAPTR records.) I was always afraid to execute regular
> expressions from untrusted third-parties, _especially_ with builtin POSIX
> regex engines, which are mostly pretty horrible.

It looks like it returns the regex pattern as a string, so presumably the calling app has to decide how to handle it.  That makes sense for telephony applications - since NAPTR is used in ENUM (RFC 3761) resolution, as well as calling name based on a popular draft, among other more proprietary uses.  Regardless, the "original" string to apply the regex to, and replace its matched portion, is only truly known by the upper-layer calling application. (ie, it's not the DNS query key)  And of course letting the calling application do it means it can make some decisions about whether to only handle regex patterns it knows about in-advance (which some telephony vendors do), or optimize for common ones, or truly compile it on the fly, or whatever.

-hadriel


Reply | Threaded
Open this post in threaded view
|

Re: [ANN] lsocket - Another library for sockets in lua

Sean Conner
It was thus said that the Great Hadriel Kaplan once stated:
>
> On Mar 28, 2013, at 12:36 AM, William Ahern <[hidden email]> wrote:
>
> >> [3] It handles 32 DNS record types---about 26 more types than other DNS
> >> resolving libraries.

  Well, my "handles" I mean "parses the wire format and presents the record
in an easy to use format for upper level code".  

> > I can't find any code which handles NAPTR pattern matching in SPCDNS. Do you
> > just use the POSIX regex library in your applications? (Presuming you
> > actually use NAPTR records.) I was always afraid to execute regular
> > expressions from untrusted third-parties, _especially_ with builtin POSIX
> > regex engines, which are mostly pretty horrible.
>
> It looks like it returns the regex pattern as a string, so presumably the
> calling app has to decide how to handle it.  That makes sense for
> telephony applications - since NAPTR is used in ENUM (RFC 3761)
> resolution, as well as calling name based on a popular draft, among other
> more proprietary uses.  Regardless, the "original" string to apply the
> regex to, and replace its matched portion, is only truly known by the
> upper-layer calling application. (ie, it's not the DNS query key) And of
> course letting the calling application do it means it can make some
> decisions about whether to only handle regex patterns it knows about
> in-advance (which some telephony vendors do), or optimize for common ones,
> or truly compile it on the fly, or whatever.

  Yup, this is pretty much the case.  How the two projects use NAPTR records
was beyond the scope of SPCDNS; they're just happy to be able to use a
simple API (there's only two calls) to parse the DNS packets.

  -spc


Reply | Threaded
Open this post in threaded view
|

Re: Checking for rocks up

Tomás Guisasola-2
In reply to this post by Hisham
  Hi Hisham

On Wed, 27 Mar 2013, Hisham wrote:
> * Rock X has a new version 2.0, which is incompatible with previous
> version 1.5. Rock Y depended on rock X, but it didn't specify a
> version (or it was optimistic and asked for "X >= 1.0"). Rock Y
> doesn't have an updated version yet which is compatible with X 2.0.
> Now rock Y is broken.
  I thought that a move from 1.5 to 2.0 is an upgrade (which can
include incompatibilities) while a move from 1.5 to 1.5.1 is an update
(which should only correct bugs).  LuaRocks could use a more strict
definition of the version number and provide a simple way to update
packages based on the third number.  The Lua team follows this rule,
thus it does not seem to break too much code around.

  Regards,
  Tomás
Reply | Threaded
Open this post in threaded view
|

Re: Checking for rocks up

Hisham
On 2 April 2013 08:15, Tomas Guisasola Gorham <[hidden email]>
wrote:

>
>         Hi Hisham
>
>
> On Wed, 27 Mar 2013, Hisham wrote:
>>
>> * Rock X has a new version 2.0, which is incompatible with previous
>> version 1.5. Rock Y depended on rock X, but it didn't specify a
>> version (or it was optimistic and asked for "X >= 1.0"). Rock Y
>> doesn't have an updated version yet which is compatible with X 2.0.
>> Now rock Y is broken.
>
>         I thought that a move from 1.5 to 2.0 is an upgrade (which can
> include incompatibilities) while a move from 1.5 to 1.5.1 is an update
> (which should only correct bugs).  LuaRocks could use a more strict
> definition of the version number and provide a simple way to update
> packages based on the third number.  The Lua team follows this rule,
> thus it does not seem to break too much code around.

It's a great idea in principle, but each developer follows their own
numbering logic (and you know how hard (if not impossible) it is to
impose a policy like that to the Lua world at large). But yes, for
rocks within an organization, for example, it would make sense. Now
that we are talking about a revision/extensions to the rockspec
format, an idea that just crossed my mind is that the rockspec author
could mark in a release which range of previous versions it is
compatible with. Then the burden of ensuring that the upgrade won't
break would be on the rock author, and it would work fine within an
organization. For example, when releasing version 1.5.4 the rockspec
could include something like api_compatible=">= 1.5" and then an
auto-update command could check that before doing things
automatically. (We would need a very strict definition of being "API
compatible" of course.)

How does that idea sound?

-- Hisham

Reply | Threaded
Open this post in threaded view
|

RE: Checking for rocks up

Thijs Schreijer
> -----Original Message-----
> From: [hidden email] [mailto:[hidden email]] On
> Behalf Of Hisham
> Sent: dinsdag 2 april 2013 15:55
> To: Lua mailing list
> Subject: Re: Checking for rocks up
>
> On 2 April 2013 08:15, Tomas Guisasola Gorham <[hidden email]>
> wrote:
> >
> >         Hi Hisham
> >
> >
> > On Wed, 27 Mar 2013, Hisham wrote:
> >>
> >> * Rock X has a new version 2.0, which is incompatible with previous
> >> version 1.5. Rock Y depended on rock X, but it didn't specify a
> >> version (or it was optimistic and asked for "X >= 1.0"). Rock Y
> >> doesn't have an updated version yet which is compatible with X 2.0.
> >> Now rock Y is broken.
> >
> >         I thought that a move from 1.5 to 2.0 is an upgrade (which can
> > include incompatibilities) while a move from 1.5 to 1.5.1 is an update
> > (which should only correct bugs).  LuaRocks could use a more strict
> > definition of the version number and provide a simple way to update
> > packages based on the third number.  The Lua team follows this rule,
> > thus it does not seem to break too much code around.
>
> It's a great idea in principle, but each developer follows their own
> numbering logic (and you know how hard (if not impossible) it is to impose
> a policy like that to the Lua world at large). But yes, for rocks within
> an organization, for example, it would make sense. Now that we are talking
> about a revision/extensions to the rockspec format, an idea that just
> crossed my mind is that the rockspec author could mark in a release which
> range of previous versions it is compatible with. Then the burden of
> ensuring that the upgrade won't break would be on the rock author, and it
> would work fine within an organization. For example, when releasing
> version 1.5.4 the rockspec could include something like api_compatible=">=
> 1.5" and then an auto-update command could check that before doing things
> automatically. (We would need a very strict definition of being "API
> compatible" of course.)
>
> How does that idea sound?
>
> -- Hisham

My take (as a SemVer[1] advocate) would be to add a flag whether the version numbering is SemVer compatible. That would immediately take all the ambiguity out of the compatibility question.

Thijs

[1] http://semver.org
Reply | Threaded
Open this post in threaded view
|

Re: Checking for rocks up

Jay Carlson
In reply to this post by Hisham
On Apr 2, 2013, at 9:54 AM, Hisham wrote:

> On 2 April 2013 08:15, Tomas Guisasola Gorham <[hidden email]>
> wrote:
>>
>> On Wed, 27 Mar 2013, Hisham wrote:
>>>
>>> * Rock X has a new version 2.0, which is incompatible with previous
>>> version 1.5. Rock Y depended on rock X, but it didn't specify a
>>> version (or it was optimistic and asked for "X >= 1.0"). Rock Y
>>> doesn't have an updated version yet which is compatible with X 2.0.
>>> Now rock Y is broken.
>>
>>        I thought that a move from 1.5 to 2.0 is an upgrade (which can
>> include incompatibilities) while a move from 1.5 to 1.5.1 is an update
>> (which should only correct bugs).  LuaRocks could use a more strict
>> definition of the version number and provide a simple way to update
>> packages based on the third number.  The Lua team follows this rule,
>> thus it does not seem to break too much code around.
>
> It's a great idea in principle, but each developer follows their own
> numbering logic (and you know how hard (if not impossible) it is to
> impose a policy like that to the Lua world at large). But yes, for
> rocks within an organization, for example, it would make sense. Now
> that we are talking about a revision/extensions to the rockspec
> format, an idea that just crossed my mind is that the rockspec author
> could mark in a release which range of previous versions it is
> compatible with. Then the burden of ensuring that the upgrade won't
> break would be on the rock author, and it would work fine within an
> organization. For example, when releasing version 1.5.4 the rockspec
> could include something like api_compatible=">= 1.5" and then an
> auto-update command could check that before doing things
> automatically. (We would need a very strict definition of being "API
> compatible" of course.)

IMO one of the most common missing pieces of data models is subject, and by that I mean the entity making a particular statement.

I can write in a file

  This is api_compatible >= 1.5.

but the actual information you have to work with is

  Jay Carlson says, "This is api_compatible >= 1.5."

And you'll have to combine that with "I trust Jay Carlson's opinion" to get anywhere.

The source of the statement can be elided in single-authority systems; you end up with "the rock git repository says" implicit in front of everything. Then you get site-specific overrides, off-tree patches, ...and trying to work out *why* you believe statement X is impossible because you've erased all notion of situated statement.

This kind of thing is not exactly an everyday technology, but you may want to consider richer models for representing versioning even if you're going to use simple rules to collapse everything to axioms at the start of a run.

Jay
"Ontology is not the problem. Epistemology is the problem."
Reply | Threaded
Open this post in threaded view
|

Re: Checking for rocks up

Dirk Laurie-2
In reply to this post by Thijs Schreijer
2013/4/2 Thijs Schreijer <[hidden email]>:

> My take (as a SemVer[1] advocate) would be to add a flag whether
> the version numbering is SemVer compatible. That would immediately
> take all the ambiguity out of the compatibility question.
...
> [1] http://semver.org

I've read that through once. Here is my list of first impressions.
Any mistake in #2 onwards is caused by #1.

1.  It reads like the small print in a software license, but claims
    to merely nail down what everybody is (sort of) doing already.
2.  It is designed by one of the founders of GitHub.
3.  You number your sofware releases as X.Y.Z, which act like digits
    in a number system with an arbitrarily large basis, not stopping
    at 10. I.e. when X or Y ticks over, the later digits start all over
    from 0.
4.  The whole numbering idea applies only to software that is properly
    documented. Don't release anything otherwise. Keep it on GitHub by
    all means, keep developing it, even tell people abut it, just don't
    issue numbered releases.
5.  You can't re-use the same three numbers if you have changed anything.
6.  You increase X (the major release number) when you have introduced
    a backwards incompatible change, except you don't need to when
    X is still stuck at 0.
7.  You increase Y (the minor release number) when you have added new
    features but all properly documented existing features still work.
8.  You increase Z when you have corrected a bug. Any discrepancy
    between documentation and performance counts as a bug. You can
    correct it either way.
9.  Any software that depends on documented working features of X.Y.Z
    can specify its dependance as `X.Y.Z <= version < (X+1).0.0` and you
    should feel guilty when your new release with the same X breaks
    someone else's application.
10. You should in your documentation deprecate features when it is likely
    that (X+1).0.0 won't support them any more.

I think once these rules are well known and most reputable software authors
follow them, new authors will follow them too. So count this mail as a small
contribution in that direction. (And please correct mistakes in it.)

But if the author of SemVer himself does not specify such a flag, it is not
for us to do so. We can claim SemVer compliance in our documentation.

At present GitHub itself does not impose SemVer on authors, nor does it
offer any mechanism for mapping branches to major releases. In fact does
not even tell authors creating a new repository to go and read the SemVer
specs before issuing any releases.

Reply | Threaded
Open this post in threaded view
|

Re: Checking for rocks up

steve donovan
In reply to this post by Jay Carlson
On Wed, Apr 3, 2013 at 2:20 AM, Jay Carlson <[hidden email]> wrote:
  This is api_compatible >= 1.5.
but the actual information you have to work with is
  Jay Carlson says, "This is api_compatible >= 1.5."

Which is why the rockspec format needs two email fields: author and maintainer (like in LuaDist).  We may not be the most modest people on the planet, but we would hate to implicitly claim that this package is ours only.  With this small change, a packaging culture can appear.  An enthusiastic rockspec writer can then happily wrap up useful modules without confusion about authorship.

Reply | Threaded
Open this post in threaded view
|

Re: Checking for rocks up

Hisham
On 3 April 2013 02:23, steve donovan <[hidden email]> wrote:

> On Wed, Apr 3, 2013 at 2:20 AM, Jay Carlson <[hidden email]> wrote:
>>
>>   This is api_compatible >= 1.5.
>> but the actual information you have to work with is
>>   Jay Carlson says, "This is api_compatible >= 1.5."
>
>
> Which is why the rockspec format needs two email fields: author and
> maintainer (like in LuaDist).  We may not be the most modest people on the
> planet, but we would hate to implicitly claim that this package is ours
> only.  With this small change, a packaging culture can appear.  An
> enthusiastic rockspec writer can then happily wrap up useful modules without
> confusion about authorship.

"maintainer" is the entry for the rockspec maintainer. Contact
information for the authors/maintainers of the project can be obtained
through the URL in the "homepage" field (I found it a more flexible
way of doing this than "author", which implies the code is written by
a single person, which is often not the case in collaborative
environments (and an "authors" array would have complications of its
own). )

The documention does say that "maintainer" refers to ther rockspec and
not to upstream, but I still take the blame for naming the
"maintainer" field ambiguously. Sometimes verbosity is better: in
hindsight, "rockspec_maintainer" and "project_homepage" would have
been better choices.

-- Hisham
http://hisham.hm/

12