Gtk-rs release process

Given the growing complexity of gtk-rs release and the upcoming number of related questions to this topic, I thought it might be interesting to have a little post on how it worked and how it now works. I talk a bit as well of the reasons of why gtk-rs isn't a single repository.

In the old times

Like I said just above, I changed very recently how we release a new version of gtk-rs. With the following explanations, you'll understand very quickly why.

First point, the gtk-rs organization is huge in term of number of crates: we have 26 of them. Yes, 26. And the funniest part: they all depend on each other, but that's not all! The current architecture is as follow:

• Each crate has a sys-crate (where we put all C functions and types).
• Each repository has a crate branch (which corresponds to the current released crate) and a master branch (which is the development branch). (Though there is an exception here: the examples repository has a pending branch and master corresponds to the current relese.)

So the first step is to update the crate version inside the master branches and update all its gtk-rs dependencies' version as well.

Then we merge changes from the master branches into the crate branches.

Next, we open pull requests to the crate branches.

Once all pull requests have been merged, we publish all crates to crates.io (in a specific order, otherwise it doesn't work because of dependencies), starting from sys-crates.

Good, seems like we're mostly done, no? What could be missing? Oh, the documentation!

Generating documentation

Let's update it then! For every non-sys crates, we have to generate the documentation by enabling all features. Some of you may have notice it, but gtk-rs repositories don't contain documentation in their source code. The reason is simple: for licensing issues, we store all of them in a specific repository: lgpl-docs.

In the old times of gtk-rs, I wrote a tool (with the great help of gkoz!) to add and remove documentation from a Rust source code: rustdoc-stripper. We use it to put back the documentation before generating it.

Once done, we push, make a pull request and merge it. That's it, the documentation has been updated as well!

Now two things are remaining:

1. Updating the gtk-rs.org website (the version badges).
2. Writing a shiny blog post announcing how awesome gtk-rs contributors are!

The first one is quite quick to be done, the second one a lot less (Thank you so much @EPashkin for helping me doing it! T_T).

From all this, I assume you now have understood how much time a release took, right? Then, here comes the great improvement!

Automation

It might seems stupid to say it, even more considering how much it took me to just make one release, but writing a (huge) script to handle the whole release allowed me to earn A LOT of time. You can find it here: gtk-rs/release.

Now you might wonder why I didn't do it ages ago, right? Well, because writing this script was really long and painful (I mean, testing a release of 26 crates...). It's now running correctly and a release can be done in less than an hour.

It now does everything on its own:

• Updating versions and dependencies.
• Opening pull requests.
• Building documentation (correctly, which is a huge improvement compared to before!).
• Updating website and getting all merged pull requests for this release to write the blog post more quickly (I cheated a bit in here, I already wrote this for this week in rust docs :p).

In the future, I think I'll add tags for repositories as well. Not sure if it's really necessary but people might be interested, so why not?

gtk-rscode>-a-single-repository?">Why not make gtk-rscode> a single repository?

Since I wrote this blog post, I decided to answer this question at the same time. Enjoy! :)

So "Why not make gtk-rs a single repository?". I had this question a lot. Funny fact: the gtk-rs was a single repository when we started. We splitted all the crates into their own repository when we created the organization. So why did we change?

For multiple reasons:

• The codebase was starting to be really huge.
• It had A LOT of issues and pull requests and it was hard to get which corresponded to what.
• It didn't represent really well the gtk-rs architecture.

From this point, the first issue we had to fix was the tests. Yes, testing multiple repositories to see if an update from one repository didn't break another one was vital. Even now, it's still incomplete but we made improvements.

Apart from the previous reason, we didn't see any other one which would make us want to go back to one repository. The release would still be horrible and the repository would be way too huge and horrible to manage.

Conclusion

As you can see, a gtk-rs release is quite exhausting. It got better, but a lot of work remain to be done.

However, despite all this, I really like what we did with gtk-rs and I will never thank enough the people who made it what it is now. Thank you! :)

Posted on the 07/09/2017 at 23:00 by @GuillaumeGomez

Next article

New rustdoc rendering common errors

Previous article

Little tour of multiple iterators implementation in Rust

Back to articles list