Automated release notes / blog posts

discussion

#1

At this point we have quite lean publishing of release announcements. However (from my own experience as a maintainer of several modules) it’s sometimes not only cumbersome but challenging to write something more that what is automatically generated. There are several reasons for that, but the most important is that at the point when given component is released you don’t really remember what were the highlights and why they are worth mentioning besides automated issues list.

So I came up with the idea of making “the process” better. Here’s what I have in mind:

  • Every important commit going to master is titled in a shape that it can be re-used (or slightly rephrased)
  • If particular commit has a git note attached to it in the namespace of refs/notes/blog then it should be considered as something automatically pulled to the blog announcement

This has main benefit of announcing the release at the same time as it actually happens (hopefully after mvn central gets synced :D) with (hopefully) appealing content.

Now there is one open questions I would like to gather some feedback about (besides the one if you find this idea useful)

  • What if there are no notes? Shall we just do regular automated announcement?

@aslak Can you point me to the release announcement generator code? Are we also synced with Twitter to spread the word even more?


Website improvements
Building all the things Arquillian
#2

The general ‘make a release page code’ is here: https://github.com/arquillian/arquillian.github.com/blob/develop/_ext/releases.rb

The template is here: https://github.com/arquillian/arquillian.github.com/blob/develop/_layouts/release.html.haml

And most of the logic around data extraction can be found here: https://github.com/arquillian/arquillian.github.com/blob/develop/_ext/arquillian.rb

Personally I’m skeptical to git notes as they need to be pushed separately and probably more cumbersome. A highlight label on an issue that is within the same milestone as being released, possible with a ‘special comment’ or something sounds easier to deal with for most.


#3

Personally I’m skeptical to git notes as they need to be pushed separately and probably more cumbersome.

This can be easily dealt with by some simple alias. The same with tags :slight_smile: And I guess it will be the maintainer anyway who will be bringing the commits to master and thus the description based on the PR and alike. My only goal here is to have it on time when we release. On top of that you can have asciidoc rich description.


#4

Hi,
I think that it’s great idea to generate more information automatically; but, to be honest, I haven’t used git notes yet. For important or bigger commits I usually use the extended (longer) commit messages. I think that there are a few things that should be considered:

  1. Where this information should be displayed - together with the commits or separately? I would vote for showing them together. If it was separated then it would require additional effort for rephrasing to make the text clear, fluent and meaningful - this would have to be done by the blog maintainer (by Aslak or by you) because I don’t know about anyone who have succeeded in running the project (arquillian.github.com) locally (except for Aslak).

  2. Usually one functionality that should be mentioned in the blog post consists of more than one commit. So, I guess that the note should be attached to the last commit that implements the functionality, right? Or it should be described incrementally?

  3. Isn’t better to retrieve and parse the extended commit messages?

I’ve got these concerns because I don’t have any experience with git notes and I cannot imagine the process of retrieving and formatting the texts… I’m not against it I don’t have problem with learning and trying new things I’m just afraid that the effort will be bigger than the results (not only for the commiters but also for the blog mainainer)…


#5

That’s what was my spare time quest over last few days… And I think I’ve finally managed to provide working docker solution. Hopefully it will work on your machines too :slight_smile:https://github.com/arquillian/arquillian.github.com#dockerized-setup

As for the rest of your questions Matous - let me first run a small spike in the coming days and I will share my findings.


#6

Not sure you want to go there, but on the arquillian-container-was branch I’ve used wercker to create a reproducible build with a docker base container and wercker.yml file that everyone, including the build server can use.

I used a similar approach for building our company’s website and this allows everyone to build the site locally and also ensures that the build server executes exactly the same and automatically publishes the site.

Just me 2 cents on this; I think the minimum should be that everyone should be able to build the website with a single command. Whether that command downloads the whole internet is another issue :wink:


#7

Thanks for sharing wercker @gpoul!

I think the minimum should be that everyone should be able to build the website with a single command

That’s the whole goal of having it in the container so that you don’t have to bother about the setup at all. Moving it to the build server is another step which I definitely have to take very soon.

Besides downloading the whole internet, there is another issue for local development at this point - you have to have github-token configured in order to have a successful build, as we are reading a lot of metadata from there. You presumably need to be part of the Arquillian organization to be able to gather it.

This is in my eyes a blocker for external contributors who ideally would like to see their post/guide etc without bothering about the rest.

So as you can see the quest to single, simple command is not only about the tooling per se, it’s also making the code base not so interdependent. We will get there :slight_smile: