Release procedure and policy

[kamalmarhubi]

As far as I know, only @carllerche can make releases. We need to figure out a procedure that works for the active maintainers.

We should also come up with a release schedule. There have been over 100 commits since the last release, which was less than two months ago, so we're probably averaging ~10 commits per week.

@fiveop proposed every other week or so in #290 (comment). I'm in favour of a fairly quick cycle to make sure changes are routinely getting onto crates.io.

Depending on how careful we are or want to be, we can mostly make 0.0.1 bumps except on API changes. Or we can just always make 0.1.0 bumps. I don't have strong feelings.

[posborne]

I'm in favor of a faster release cycle, particularly when users report issues and work to get a PR merged. In those cases, the reporter has probably already been inconvenienced by bumping into the issue and it is nice to provide a release in a timely fashion. Doing releases more frequently reduce the overall impact of cutting a release (smaller deltas).

I think we should try to follow semantic versioning and let that dictate how we do version bumps.

Adding the nix core team to the crate but leaving @carllerche as the named owner (although I would nominate @kamalmarhubi as a potential co-named owner) seems to make sense to me so long as there is a documented release process in place that we can all follow (PR with changelog prior to release perhaps approved by another core team member). There is pretty good documentation on team ownership here: http://doc.crates.io/crates-io.html#cargo-owner

[carllerche]

Happy to do whatever, let me know

[posborne]

@nix-rust/nix-maintainers Any other thoughts? I'm currently in favor of granting co-named ownership to @kamalmarhubi and team ownership to @nix-rust/nix-maintainers. Any objections?

[kamalmarhubi]

I have no thoughts other than let's be able to make releases! @carllerche could you run at least the following command:

cargo owner --add github:nix-rust:maintainers

More docs here: http://doc.crates.io/crates-io.html#cargo-owner as linked above. I have no strong feelings either way on whether I'm otherwise named as an owner.

[posborne]

Agreed. We need to cut a release. @carllerche I aggree with @kamalmarhubi that getting the maintainers access should be enough to get the ball rolling.

[kamalmarhubi]

@carllerche gave it a shot, but was not having luck with GitHub permissions. I opened up the nix-rust org but I don't think he had a chance to try it again. This is a crates.io usability pain point for sure.

[kamalmarhubi]

We can now release! I just put up a v0.6.0 at current master + changes to make the release (actual changes in #378). This was important because we were blocking a Rust change: rust-lang/rust#34198 (comment).

Not sure how best to actually do the release dance, but at least now we can!

[fiveop]

#383 reminded me: keeping a change log for breaking changes, seperate from the commit history, would would be helpful for users of the library

[posborne]

#383 reminded me: keeping a change log for breaking changes, seperate from the commit history, would would be helpful for users of the library

Agreed. I'm fine with either trying to maintain this along the way (as a part of PRs) or gathering it up at release time (some amount of work will already be required at this stage). That is, I probably wouldn't gate PRs on updating the release notes (especially for new contributors). Here's an example of what I try to maintain on my projects: https://github.com/rust-embedded/rust-sysfs-gpio/blob/master/CHANGELOG.md which is based on https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md.

[fiveop]

Excellent, now we only need an RFC, aprove it, adjust the CONVETIONS, and create an initial change log(prefereably, already going back to the first version).

[fiveop]

Additional point that came up in rust-lang/libc#333: We should use the Github version of libc for development and a fixed version for releases.

[alexcrichton]

Ah and just to clarify, I don't mind making a libc release whenever. I figured it'd just be easier where if nix changes require also landing libc changes to not block on a libc release. That way nix could use the git version of libc for the latest-and-greatest APIs, and then whenever it's time for a nix release we can make sure to make a libc release.

[kamalmarhubi]

@fiveop

create an initial change log(prefereably, already going back to the first version).

This sounds a bit ambitious! There are 25 versions... I think we can probably pull together something for 0.4.x -> 0.5 and onwards, which is 3 versions. In rust-lang/rust#34198 (comment) it was revealed that only one published crate had a dependency on 0.3.x, so going that far back isn't really worth the effort in my opinion.

[fiveop]

I agree.

[fiveop]

One small point for our release procedures: bump the version in README.md.

[kamalmarhubi]

Yeah. Also there's a bit of a double commit dance for the Cargo.toml version at the moment: bump to remove -dev, and bump again to add -dev. And tagging, also important.

[nox]

Why do we need the -pre version at all? No other projects do that and they seem to do just fine.

[fiveop]

The idea is, that only the repository state that gets released as a proper version in it. I am not sure, whether it helps much, but I don't think that it hurts either.

[fiveop]

Btw. can we close this now? We have a documentation on how to get a release. If we want to discuss any other subject related to this topic, for example a schedule, we should open a fresh issue anyway.

[nox]

This is the only crate behaving this way, so I would say the fact that no other crates ever needed this show that this is just unnecessary ceremony. Plus, that means we can never [replace] this dependency with a PR of it or whatever, given it will have a different version number as the crate released on crates.io.

[fiveop]

I opened issue #468 for @nox's concerns and close this issue now.