Versioning scheme for rdma-plumbing

Versioning scheme for rdma-plumbing

[Jason Gunthorpe]

Hi all,

Here are my thoughts on how to version this thing. I've completed the
proposed Debian packaging to the point of being lintian clean and now
have a reasonable idea what their sensitivies are.

I've written a small file discussing the issue here:

https://github.com/jgunthorpe/rdma-plumbing/blob/master/Documentation/versioning.md

The gist is, I recommend using a single increasing integer for the
overall tree. I think udev popularized this scheme for stable plumbing.

The shlibs files will become sensibly labeled using a semantic style
soname.abi.release scheme. Eg the next release of libibverbs (assuming
no ABI change) would be 'libibverbs.so.1.2.11', (with the usual link
from 'libibverbs.so.1').

This conveys actual information now, '1.2' indicates that @IBVERBS_1.2
and better symbols are present, and '11' indicates it is release 11 of
the overall tree.

These file names serve no functional purpose (we have used
libibverbs.so.1.0.0 forever), so this is all bikeshedding - but
distros that package the libraries seperately (eg debian) should have
sensible versions for them, and this is a forumula to get there.

We will start applying symbol versions and ABI versioning sanely, so
if new ABI symbols are added they will be correctly tagged eg
@IBVERBS_1.3 and the libibverbs version will change to '1.3.11' and so
on. This will make RPM work properly.

umad has released 1.3.10.1, so I'm suggesting sarting at '11'. There
is no particularly strong reason for that. (since libibumad3's package
version will change to 3.1.XX anyhow)

As debian uses a split package it will then use the above scheme for
shared libary package versions:

 libibverbs1 1.2.11-1
 libibumad3 3.1.11-1
 librdmacm1 1.1.11-1

And use the overall release number for other things:

 ibverbs-utils 11-1

This is all largely automated.

The providers are versioned with the top level, there is no longer an
place to put a provider specific version, nor do I think it is desired
for the same reason we don't like it in the kernel..

I thought about using the kernel version, but we are not so strongly
linked to the kernel to make that really useful, and it makes the
names longer..

Thoughts?

Jason
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Versioning scheme for rdma-plumbing

[Christoph Hellwig]

Hi Jason,

thanks for the writeup.  Versioning is always a bit of a bikeshedding
exercise, but I'd still vote for following the kernel versioning (while
fully agreeing with your thiughts on shared library versioning).

Two reasons for that:

 - it's a good marker of what version of the userspace code you need
   to take advtantage of new kernel features
 - it allows for much smoother minor updates.  I hope this will be
   rare, but my experience from various projects tells me that they
   will occasionally be needed.
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Versioning scheme for rdma-plumbing

[Jason Gunthorpe]

On Wed, Sep 14, 2016 at 05:28:20AM -0700, Christoph Hellwig wrote:
> Hi Jason,
> 
> thanks for the writeup.  Versioning is always a bit of a bikeshedding
> exercise, but I'd still vote for following the kernel versioning (while
> fully agreeing with your thiughts on shared library versioning).

I'm having a hard time preferring one choice over the other.

If we use the kernel version then the shlibs will progress like:

 libibverbs1 1.2.4.8-1
 libibverbs1 1.3.4.9-1

I don't see a problem with that, even if it does look a bit strange.

> Two reasons for that:
> 
>  - it's a good marker of what version of the userspace code you need
>    to take advtantage of new kernel features

Most users are running EL distros and their kernels are full of
backports. So the number doesn't help them. Perhaps it could help the
distros?

>  - it allows for much smoother minor updates.  I hope this will be
>    rare, but my experience from various projects tells me that they
>    will occasionally be needed.

Can you explain this some more?

If we use a single integer ala udev, I'd see minor updates, LTS
branch, etc being released with a suffix eg: 123.2

Jason
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Versioning scheme for rdma-plumbing

[Jarod Wilson]

On Wed, Sep 14, 2016 at 11:33:27AM -0600, Jason Gunthorpe wrote:
> On Wed, Sep 14, 2016 at 05:28:20AM -0700, Christoph Hellwig wrote:
> > Hi Jason,
> > 
> > thanks for the writeup.  Versioning is always a bit of a bikeshedding
> > exercise, but I'd still vote for following the kernel versioning (while
> > fully agreeing with your thiughts on shared library versioning).
> 
> I'm having a hard time preferring one choice over the other.
> 
> If we use the kernel version then the shlibs will progress like:
> 
>  libibverbs1 1.2.4.8-1
>  libibverbs1 1.3.4.9-1
> 
> I don't see a problem with that, even if it does look a bit strange.
> 
> > Two reasons for that:
> > 
> >  - it's a good marker of what version of the userspace code you need
> >    to take advtantage of new kernel features
> 
> Most users are running EL distros and their kernels are full of
> backports. So the number doesn't help them. Perhaps it could help the
> distros?

It's actually useful. We tend to backport "up to kernel v4.x", so the
kernelspace drivers would match up well enough with the libibverbs with a
version number matching that. We actually have one userspace glue thing
that Doug mentioned earlier, which uses exactly that scheme for it's
versioning.

-- 
Jarod Wilson
jarod-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org

--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Versioning scheme for rdma-plumbing

[Jason Gunthorpe]

On Wed, Sep 14, 2016 at 03:53:35PM -0400, Jarod Wilson wrote:

> It's actually useful. We tend to backport "up to kernel v4.x", so the
> kernelspace drivers would match up well enough with the libibverbs with a
> version number matching that. We actually have one userspace glue thing
> that Doug mentioned earlier, which uses exactly that scheme for it's
> versioning.

Humm to be clear, it would be more like '4.9 works with at least
kernel 4.9, but may not enable all features'. So you might still end
up using the 4.10 release to go with your backported 4.9 patches, for
example.

Perhaps that is the strongest argument not to use this versioning
scheme as it encourages artificial rushing to hit an arbitary version
number.. (as Greg KH complains about with the stable kernels)

Then again, perhaps we shouldn't be accepting the kernel side of
something if the user side isn't ready??

Unclear..

Jason
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Versioning scheme for rdma-plumbing

[Knut Omang]

On Wed, 2016-09-14 at 14:32 -0600, Jason Gunthorpe wrote:
> On Wed, Sep 14, 2016 at 03:53:35PM -0400, Jarod Wilson wrote:
> 
> > It's actually useful. We tend to backport "up to kernel v4.x", so the
> > kernelspace drivers would match up well enough with the libibverbs with a
> > version number matching that. We actually have one userspace glue thing
> > that Doug mentioned earlier, which uses exactly that scheme for it's
> > versioning.
> 
> Humm to be clear, it would be more like '4.9 works with at least
> kernel 4.9, but may not enable all features'. So you might still end
> up using the 4.10 release to go with your backported 4.9 patches, for
> example.
> 
> Perhaps that is the strongest argument not to use this versioning
> scheme as it encourages artificial rushing to hit an arbitary version
> number.. (as Greg KH complains about with the stable kernels)
> 
> Then again, perhaps we shouldn't be accepting the kernel side of
> something if the user side isn't ready??

I think it is important to realize that the version numbering itself 
affects how people not intimately involved perceive stability and compatibility
of the versioned component.

I think if we go for a tie to the kernel version, people will expect versions 
to match kernel version, with pressure to update the (major) versions
even when content or API has not changed significantly. 

If on the other hand a separate versioning scheme is kept, the version numbering
will end up closer reflecting the intrusiveness of the actual changes made. 

Based on this reasoning, I'd definitely vote for the separate versioning.

Thanks,
Knut

> 
> Unclear..
> 
> Jason
> --
> To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
> the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Versioning scheme for rdma-plumbing

[Christoph Hellwig]

On Wed, Sep 14, 2016 at 11:33:27AM -0600, Jason Gunthorpe wrote:
> >  - it allows for much smoother minor updates.  I hope this will be
> >    rare, but my experience from various projects tells me that they
> >    will occasionally be needed.
> 
> Can you explain this some more?
> 
> If we use a single integer ala udev, I'd see minor updates, LTS
> branch, etc being released with a suffix eg: 123.2

Well, that's not a monotonically increasing version number anymore.
And at least in the past systemd folks argued against even doing these
releases.  If you're fine with doing minor releases off these single
component versions this argument goes away of course.
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Versioning scheme for rdma-plumbing

[Jason Gunthorpe]

On Wed, Sep 14, 2016 at 11:15:09PM -0700, Christoph Hellwig wrote:
> On Wed, Sep 14, 2016 at 11:33:27AM -0600, Jason Gunthorpe wrote:
> > >  - it allows for much smoother minor updates.  I hope this will be
> > >    rare, but my experience from various projects tells me that they
> > >    will occasionally be needed.
> > 
> > Can you explain this some more?
> > 
> > If we use a single integer ala udev, I'd see minor updates, LTS
> > branch, etc being released with a suffix eg: 123.2
> 
> Well, that's not a monotonically increasing version number anymore.
> And at least in the past systemd folks argued against even doing these
> releases.  If you're fine with doing minor releases off these single
> component versions this argument goes away of course.

Yah, I wouldn't as strict as what you are describing.

The 'single integer' is really semantic versioning with the 'MAJOR'
stripped off, since a project goal is to not make incompatable
changes.

Most upstream releases should be of the 'add functionality in a
backwards-compatible manner' and should just increment the
integer. Upstream can always increment the integer

If upstream botches a release then it might make a quick 123.1, but
generally upstream would not be in the buisness of backporting fixes
from N to N-1.

*However* I think we should make room for the people to collaborate
on a LTS branch that would use the .X nomenclature. Much like in the
kernel Linus doesn't maintain the -stable, but makes space for the
people who do.

eg perhaps the OFED team would be willing to direct their energies
upstream and maintain a public stable branch for the duration of their
release cylce ?

Jason
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: Versioning scheme for rdma-plumbing

[Christoph Hellwig]

On Thu, Sep 15, 2016 at 10:02:23AM -0600, Jason Gunthorpe wrote:
> *However* I think we should make room for the people to collaborate
> on a LTS branch that would use the .X nomenclature. Much like in the
> kernel Linus doesn't maintain the -stable, but makes space for the
> people who do.

Agreed!

> eg perhaps the OFED team would be willing to direct their energies
> upstream and maintain a public stable branch for the duration of their
> release cylce ?

That would be extremely helpful.
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html