Release Management Process


(Fletcher) #1

@jojolepro It sounds like you handle the process of building releases. Could you put a summary here of what steps you follow?


(Joël Lupien) #2

Release process of 0.8 by Xaeroxe. Modified for 0.9 and 0.10 by Jojolepro.

  1. Pick a release candidate.

  2. Test this release candidate on all three major platforms using the pong, ui and renderable example.
    Look for rendering issues and other things.

  3. Check all of the documentation, is there anything that just plain isn’t documented?
    Beware of people writing /// with nothing in the actual doc comment.
    This sometimes happens to bypass the doc warning.

  4. Check the book, does it all make sense and is up to date?

  5. Review and update the changelog. I guarantee there’s going to be at least a few missing entries.
    Use the following search query on git to see all merged pull requests: is:pr is:merged merged:>YYYY-MM-DD

  6. Check all the version numbers in the software. Are breaking crate updates marked accordingly? Are all the winit version numbers the same?

  7. Ok, we’re happy with the software now and are confident in our release candidate.

  8. Bump the versions of all amethyst* crates by 0.1.* in each Cargo.toml file.

  9. Go into each subcrate except amethyst_core and run cargo publish. You have to start with the ones not depending on other amethyst crates, then work your way up the dependency tree.
    i.e, you need to publish amethyst_assets before amethyst_renderer, because amethyst_renderer now depends on an unreleased version of amethyst_assets.

  10. Go into amethyst_core and run cargo publish --no-verify

  11. Go into the root amethyst folder and cargo publish.

  12. Tag a new release on the Amethyst github, copy/paste the changelog entry for this release into the description for the Github release.

  13. Bump up the patch version of amethyst_tools in the tools repository and publish it with cargo publish.

  14. Publish the release post on the website.

  15. Advertise the release post.


(Fletcher) #3

Awesome, thank you.

Is there any part of this that is automated yet?


(Joël Lupien) #4

Not at all.

Here’s the diff for the next release by the way: https://github.com/amethyst/amethyst/pulls?page=1&q=is%3Apr+is%3Amerged+merged%3A>%3D2018-10-22&utf8=✓


(Ellie Fagerberg) #5

I’ve said this before, but I think that we should start utilizing concourse for deployment where it can be done very nicely in stages. For example, you can have a pipeline where the artifact gets built and then is deployed as a release candidate. If everyone then thinks it’s good, the same artifact continues through the pipeline and gets deployed as the real deal. Utilizing that process, we could have more frequent and more stable releases along with potentially beta and release candidate releases.


(Fletcher) #6

@Ellie I’ve not used Concourse. If you’ve used Jenkins, could you give me a quick overview of why Concourse is better?


(Thomas Schaller) #7

One thing I’d love about this would be having nightlies that people can use instead of depending on master. So I’m all for this :+1:


(Fletcher) #8

(I only pick Jenkins because it is the only other thing I know besides Spinnaker that could do this)


(Ellie Fagerberg) #9

@fletcher I haven’t used Jenkins unfortunately but I think in our case, Concourse is better just because we already have it up and running.

About the nightly releases, I think it would be absolutely fantastic to have them. What I’m unsure about is where and how we should release them. If we release on crates.io then it would have to be as a separate package in order to not clutter up the main package releases which could confuse new people. It would also mean that any dependencies that depend on Amethyst would break. I’m instead inclined to make depending on a git repo a little bit nicer with proper release mechanisms. So instead of replacing the entire Amethyst dependency for a git repo, we would instead encourage people to depend on the latest release and patch in the beta or nightly release through linking to a separate repo (perhaps something like GH/amethyst/beta) where we make sure the contents are always tested before they’re released.


(Joël Lupien) #10

If you automate the release process on your ci server, expect it to take around 6 hours to build everything.


(Fletcher) #11

Concourse requires privileged mode for its worker container, effectively giving it root access to the box, which can then be used to pivot into the rest of the network. Will have to think about this and possible solutions.


(Ellie Fagerberg) #12

It does require that to be able to spawn other containers, yes. However, people can’t actually utilize it since their code is only run in runner containers which need manual approval if they’re gonna be privileged.


(Thomas Schaller) #13

One option to release “nightlies” on crates.io would be following a similar pattern as e.g. futures / futures-preview. So we’d just add -preview to the published name (only the package, the crate stays the same).

EDIT: their docs on crates.io are a bit outdated…

Since versions for packages can be arbitrary, we could then publish daily (could look something like 0.9.0-2018-11-21).


(Thomas Schaller) #14

Our release is scheduled for the 27th (Tuesday).

Concerns:

  1. @jojolepro - prefers working

I don’t think this is a big problem, since the work should be done early in any case, so that works together.

  1. @fhaynes - Blog posts get the most attention on Mondays

That’s a fair point to consider. In that case, we’d have to move our release by 6 days, because Monday is most likely too early to release.

Is anybody opposed to moving the release from the 27th of November to 03rd of December? Or are there other suggestions?


(Joël Lupien) #15

I was working more on the mondays this summer. Now I have free time in the morning and midday on mondays. I’d propose moving the release to the 26.

Most urgent issues can be fixed within 1-2 days pretty easily.


(Fletcher) #16

Most urgent issues can be fixed within 1-2 days pretty easily.

This concerns me. I don’t think we should release a feature that had to be fixed 1-2 days before release. Can you give a quick overview of what those are?


(Thomas Schaller) #17

Even if we can fix them properly that fast (which we most likely won’t, based on data from the last two years), it still should be properly tested, documented, etc. Doing things so late usually allows mistakes to slip in more easily.


(Fletcher) #18

Even if we can fix them properly that fast (which we most likely won’t, based on data from the last two years), it still should be properly tested, documented, etc. Doing things so late usually allows mistakes to slip in more easily.

I completely agree. It would be better to leave them out and just note that those will be delayed due to unforeseen complexities. This will build a lot of trust with the user base, which is invaluable.

One of our biggest draws is going to be the safety of Rust, and I think we need to adopt that as a philosophy in general. We shouldn’t be afraid to delay a feature if needed. As long as we are open and honest about it, I think users will appreciate it.


(Joël Lupien) #19

Last release I fixed stuff on release day :smiley:

But the things that require fixing are those that I send to torkleyy earlier on discord (#internal)

Adding InputEvent to StateEvent -> doable in 10 minutes, no risk of errors. https://github.com/amethyst/amethyst/issues/1148

And the last one is https://github.com/amethyst/amethyst/pull/1164 (waiting on merge, already reviewed)

All others have been merged in the past two hours


(Thomas Schaller) #20

Well, there are other things than the issues we know about. The last week should be all about looking for those.