Publishing libgpiod-sys and libgpiod to crates.io

Publishing libgpiod-sys and libgpiod to crates.io

[Erik Schilling]

Hi all,

After merging of [1] only some cosmetics should be missing from being
able to publish to crates.io.

First, we would need to agree on a version number (or rather a
release management process). Rust is suggesting people to follow a
SemVer approach [2] and I would strongly suggest to stick to that
recommendation. We _could_ just start releasing with the next libgpiod
release and have the Rust bindings follow the libgpiod releases. While
this may seem intuitive to users (they can just spell libgpiod = 2.0.1
and reason easily about which libgpiod version is in use), it would come
with a couple of implications:

1. Users would likely expect new features of a C lib release to also be
   usable from the Rust crate if it uses the same versioning scheme.
   So this would also tie the necessary effort to expose those features
   from the Rust bindings to the release process.
2. Supporting multiple versions of the C lib with the Rust bindings
   would be no problem in general, but would become awkward when trying
   to replicate the version numbers of the C lib.
3. Changes to the Rust bindings would always require an overall version
   bump.
4. There may be a conflict between SemVer bumps for the whole of
   libgpiod vs a bump that would be required for the Rust bindings only.

This all seems pretty restrictive and undesirable to me... So I would
recommend to manage the version numbers of libgpiod and the Rust crates
libgpiod-sys and libgpiod all separately. It may help to think of the
versions of the Rust crates as ABI versions (the C lib has its own
ABI version too!). This way we could :just get started with the version
numbers starting at 0.1.0 and start bumping them as needed for both
libgpiod and libgpiod-sys independently. Also, this means that uploading
to crates.io would not be strictly coupled to the release process of the
C lib and other bindings. That may allow to spread the load a little.

This may be slightly confusing to the user, but I hope it is less
confusing than the mess of what I listed above? Any opinions?

After agreeing on a versioning strategy, actually publishing to
crates.io should only require to add version number restrictions to the
libgpiod->libgpiod-sys dependency. It will then use that version for
installs from crates.io and use the `path` when building locally.

Once that small change is also done, I think we are ready for
publishing.

@Bart: How would you prefer to handle the upload of new versions? Or
would you prefer to be the one doing it or prefer if someone from the
community handles it? I can offer to help with documentation and setup
if needed :).

[1] https://lore.kernel.org/r/20230522-crates-io-v2-0-d8de75e7f584@linaro.org/
[2] https://doc.rust-lang.org/cargo/reference/semver.html

- Erik

Re: Publishing libgpiod-sys and libgpiod to crates.io

[Manos Pitsidianakis]

Breaking changes are inevitable. The libc crate follows a nonsemver 
scheme (0.2.144 and bump the patch number by one for every release) 
which breaks stuff all the time, or at least it used to when it was at 
its early stages. There are ways to get around breakages in case of a 
crate lib being a transitive dependency but has different versions: 

https://github.com/dtolnay/semver-trick

I believe following libgpiod's version scheme directly is what would be 
best and intuitive. -sys crates are not usual crates and users know 
this. It'd be cool to not have to bump the bindings crate version but I 
don't think it's a problem. This is how openssl{,-sys} works, if I am 
not mistaken.

All in all, in crates.io follow its conventions unless there's no way to 
do so.


Manos

Re: Publishing libgpiod-sys and libgpiod to crates.io

[Bartosz Golaszewski]

On Wed, 31 May 2023 at 11:24, Erik Schilling <erik.schilling@linaro.org> wrote:
>
> Hi all,
>
> After merging of [1] only some cosmetics should be missing from being
> able to publish to crates.io.
>
> First, we would need to agree on a version number (or rather a
> release management process). Rust is suggesting people to follow a
> SemVer approach [2] and I would strongly suggest to stick to that
> recommendation. We _could_ just start releasing with the next libgpiod
> release and have the Rust bindings follow the libgpiod releases. While
> this may seem intuitive to users (they can just spell libgpiod = 2.0.1
> and reason easily about which libgpiod version is in use), it would come
> with a couple of implications:
>
> 1. Users would likely expect new features of a C lib release to also be
>    usable from the Rust crate if it uses the same versioning scheme.
>    So this would also tie the necessary effort to expose those features
>    from the Rust bindings to the release process.
> 2. Supporting multiple versions of the C lib with the Rust bindings
>    would be no problem in general, but would become awkward when trying
>    to replicate the version numbers of the C lib.
> 3. Changes to the Rust bindings would always require an overall version
>    bump.
> 4. There may be a conflict between SemVer bumps for the whole of
>    libgpiod vs a bump that would be required for the Rust bindings only.
>
> This all seems pretty restrictive and undesirable to me... So I would
> recommend to manage the version numbers of libgpiod and the Rust crates
> libgpiod-sys and libgpiod all separately. It may help to think of the
> versions of the Rust crates as ABI versions (the C lib has its own
> ABI version too!). This way we could :just get started with the version
> numbers starting at 0.1.0 and start bumping them as needed for both
> libgpiod and libgpiod-sys independently. Also, this means that uploading
> to crates.io would not be strictly coupled to the release process of the
> C lib and other bindings. That may allow to spread the load a little.
>
> This may be slightly confusing to the user, but I hope it is less
> confusing than the mess of what I listed above? Any opinions?
>
> After agreeing on a versioning strategy, actually publishing to
> crates.io should only require to add version number restrictions to the
> libgpiod->libgpiod-sys dependency. It will then use that version for
> installs from crates.io and use the `path` when building locally.
>
> Once that small change is also done, I think we are ready for
> publishing.
>
> @Bart: How would you prefer to handle the upload of new versions? Or
> would you prefer to be the one doing it or prefer if someone from the
> community handles it? I can offer to help with documentation and setup
> if needed :).
>

For versioning: I'm all for decoupling libgpiod API version from rust
bindings version. I did that for python bindings starting at 2.0
(since they've been published separately on pypi).

For uploading rust crates: I'd love if someone else could do this. I
don't care enough for rust to do a good job at it. :)

Bart

> [1] https://lore.kernel.org/r/20230522-crates-io-v2-0-d8de75e7f584@linaro.org/
> [2] https://doc.rust-lang.org/cargo/reference/semver.html
>
> - Erik

Re: Publishing libgpiod-sys and libgpiod to crates.io

[Erik Schilling]

On Wed May 31, 2023 at 1:05 PM CEST, Manos Pitsidianakis wrote:
>
> Breaking changes are inevitable. The libc crate follows a nonsemver 
> scheme (0.2.144 and bump the patch number by one for every release) 
> which breaks stuff all the time, or at least it used to when it was at 
> its early stages. There are ways to get around breakages in case of a 
> crate lib being a transitive dependency but has different versions: 
>
> https://github.com/dtolnay/semver-trick
>
> I believe following libgpiod's version scheme directly is what would be 
> best and intuitive. -sys crates are not usual crates and users know 
> this. It'd be cool to not have to bump the bindings crate version but I 
> don't think it's a problem.

How would you deal with the libgpiod (Rust) -> libgpiod (C) dependency
here? Should we request an exact match via pkg-config (or at least a
lower floor that would equal the version of the C lib?).

I think that there would be no good reason not to support older versions
of the C lib (at least as long as sensible!). But it may be a bit weird
if the Rust crate has a matching version scheme but then automatically
disables features when building against an older system library... A
separate version scheme might make that a little more explicit. But I
got no particularly strong feelings about this.

> This is how openssl{,-sys} works, if I am  not mistaken.

openssl does not seem to follow this for neither -sys, nor the main
package. It would also probably be a weird thing to do since it supports
other backends like boringssl.


> All in all, in crates.io follow its conventions unless there's no way to 
> do so.

I think all of the options that I listed in my initial mail would follow
the crates.io conventions and I strongly agree that we should follow the
existing conventions. What to pick seems to mostly depend on how we want
the release process to look like.

- Erik

Re: Publishing libgpiod-sys and libgpiod to crates.io

[Viresh Kumar]

On 31-05-23, 19:33, Erik Schilling wrote:
> Viresh: Shall we spread the load? I am happy to set everything up.
> But it would be good to have someone else on the list who is using the
> bindings actively. :)

Please go ahead :)

-- 
viresh