Publish release notes

[Bukama]

Moved from junit-pioneer #97 as we decided to move all web site related issues.

@nicolaiparlog wrote:

Shipkit generates release notes in ./docs/release-notes.md. We should look into publishing them, maybe after manual editing, on junit-pioneer.org. This could be non-trivial because we're currently working with Asciidoc files and I have no idea how Jekyll reacts to mixing Markdown and Asciidoc and neither do I know whether it would be possible to have Shipkit generate Asciidoc.

Turns out we're already mixing Markdown with Asciidoc (because Liquid tags only seem to be processed in Markdown files), so that's not a problem.

A problem is that Shipkit adds the release notes in a commit that does not trigger a build and so these information are not actually available when the page is built. It would make sense to have only Shipkit builds trigger a page rebuilt because only than something actually changed.

Further information: Issue was linked to junit-pioneer #193 (Evaluate shipkit)

[Bukama]

We were thinking about using a starting rocket image for the button: Here are two with a dark background

https://unsplash.com/photos/n463SoeSiVY https://unsplash.com/photos/NC37HQXdpZ0

Button label could be "Lift up" - relating to the thought about you want to upgrade to a new version

[Bukama]

Work in progress on today's stream, so assigning it to @nicolaiparlog

[nipafx]

My original idea was to take the release notes as generated by Shipkit and process them:

• add headers for major versions
• change existing header levels
• intersperse text from another file to describe new features, deprecations, etc.

This proved to be a bit of work, though, and didn't add much value over simply pointing to the Shipkit-generated versions on GitHub, which we can still always edit manually.

Just in case we change our minds, here's what we got so far:

task removeReleaseNotes() {
    doLast {
        description 'Deletes specific lines in site-source/_pages/release-notes.md'
        File releaseNotes = file('site-source/_pages/release-notes.md')
        String fullReleaseNotes = releaseNotes.getText()
        String removedReleaseNotes = fullReleaseNotes.replaceAll(/(?m)<\!-- @xp:start -->$\s(^.*$\s)*^<\!-- @xp:end -->/, "<!-- @xp:start -->\n<!-- @xp:end -->")
        releaseNotes.setText(removedReleaseNotes)
    }
}

task insertReleaseNotes() {
    doLast {
        description 'Inserts XP release notes into site-source/_pages/release-notes.md'
        String releaseNoteContent = file('junit-pioneer/docs/release-notes.md').getText()
        File releaseNoteTarget = file('site-source/_pages/release-notes.md')
        String emptyReleaseNotes = releaseNoteTarget.getText()

        // no regex here because the release notes can contain symbols that conflict with regex syntax
        //  replaceAll(/(?m)<\!-- @xp:start -->$\s^<\!-- @xp:end -->/, "<!-- @xp:start -->\n${releaseNoteContent}\n<!-- @xp:end -->")
        int introEnd = emptyReleaseNotes.indexOf("<!-- @xp:start -->") + "<!-- @xp:start -->".length()
        int outroStart = emptyReleaseNotes.indexOf("<!-- @xp:end -->")
        String fullReleaseNotes = emptyReleaseNotes.take(introEnd) + "\n" + releaseNoteContent + emptyReleaseNotes.drop(outroStart)
        releaseNoteTarget.setText(fullReleaseNotes)
    }
}

[nipafx]

As explained, we just link to GitHub.

[nipafx]

I just added it to the feature row on the front page, but that's probably the least important place for them to be because that may be replaced with blog posts, features docs or whatever. Other possible places to link:

• top menu
• landing page header
• "About project" page

[Bukama]

I vote for:

• top menu ✔️
• landing page header ✔️ (also additional to top menu)
• "About project" page 🔴

[Michael1993]

I vote for:

• [X] top menu
• [ ] landing page header
• [ ] "About project" page

[nipafx]

My vote:

• [X] top menu
• [ ] landing page header
• [ ] "About project" page