YAML based LTS changelog #661

daniel-beck · 2017-02-16T01:18:20Z

Making the changelog less… HTML.

rtyler · 2017-02-16T01:24:18Z

so wait, can we merge this or not?

olivergondza · 2017-02-16T08:07:53Z

I wanted to propose structured changelog format myself so I really like this. How about the weekly changelog? Since I process them automatically, I would appreciate if the switch is fast and done on both places.

olivergondza · 2017-02-16T08:05:40Z

content/_data/changelogs/lts.yml

+      pull: 2674
+    - type: bug
+      message: Properties were _not_ passed to Maven command by Maven build step when the Inject Build Variables flag was not set
+      issue: 39268


Imo we should use JENKINS-39268 here.

I grepped the weekly changelog and found 0 referenced to other projects JIRAs. So I guess this is not such a problem after all.

oleg-nenashev · 2017-02-16T08:15:38Z

@olivergondza @daniel-beck
I'm perfectly fine with the change. Actually for a long time I was going to propose migrating to a structured Markdown. I already have a PoC for it's parsing based on the Vandamme parser's standard release notes syntax. I have a PoC, but I have not moved the remoting logs yet.

Advantages of Markdown:

Just a standard format, we can implement the PR builder for verification
Logs will be readable in GitHub

oleg-nenashev · 2017-02-16T08:18:42Z

Off-topic: Here is an example of remoting changelogs PoC:

## 2.60 / 2016-06-10

Release date: (Coming Soon)

* [BUGFIX] [JENKINS-22722](https://issues.jenkins-ci.org/browse/JENKINS-22722) - 
Make the channel reader tolerant against Socket timeouts. 
(https://github.com/jenkinsci/remoting/pull/80)
* [BUGFIX] [JENKINS-32326](https://issues.jenkins-ci.org/browse/JENKINS-32326) - 
Support no_proxy environment variable. 
(https://github.com/jenkinsci/remoting/pull/84)
* [BUGFIX] [JENKINS-35190](https://issues.jenkins-ci.org/browse/JENKINS-35190)  - 
Do not invoke PingFailureAnalyzer for agent=>master ping failures. 
(https://github.com/jenkinsci/remoting/pull/85)
* [BUGFIX] [JENKINS-31256](https://issues.jenkins-ci.org/browse/JENKINS-31256) - 
 <code>hudson.Remoting.Engine#waitForServerToBack</code> now uses credentials for connection. 
(https://github.com/jenkinsci/remoting/pull/87)
* [BUGFIX] [JENKINS-35494](https://issues.jenkins-ci.org/browse/JENKINS-35494) - 
Fix issues in file management in <code>hudson.remoting.Launcher</code> (main executable class). 
(https://github.com/jenkinsci/remoting/pull/88)
* [ENHANCEMENT] Ensure a message is logged if remoting fails to override the default <code>ClassFilter</code>. 
(https://github.com/jenkinsci/remoting/pull/80)

## 2.59 / 2016-05-13

Release date: (May 13, 2016) => Jenkins 2.4

* [ENHANCEMENT] [JENKINS-34819](https://issues.jenkins-ci.org/browse/JENKINS-34819) - 
Allow disabling the remoting protocols individually. Works around issues like [JENKINS-34121](https://issues.jenkins-ci.org/browse/JENKINS-34121) 
(https://github.com/jenkinsci/remoting/pull/83)

olivergondza · 2017-02-16T09:10:35Z

It seems to me that using url as the only kind of reference will simplify the generation a lot, made is easier for automated consumers to process and made it readable from plaintext (with full links). We can always play smart on jenkins.io and extract the type (PR/issue) from URL if it is worth it at all.

@daniel-beck, wdyt?

daniel-beck · 2017-02-16T10:59:39Z

How about the weekly changelog?

The major challenge here is moving the content over. If I somehow manage to show output for a combined new YML changelogs / old HTML changelogs output, this should be trivial. If we need to convert everything before switching over, this is going to be more difficult.

It seems to me that using url as the only kind of reference will simplify the generation a lot, made is easier for automated consumers to process and made it readable from plaintext (with full links).

I wanted an actual data format here, without it concerned about the (vast majority) of semantically useless URLs. That's why pull and issue exist. That's also why there's no JENKINS- prefix as it's implied what kind of issue this is. For nondefault behavior (more than one reference, references other than JENKINS issue or PR), there's always the references section and generic url/title pairs.

So, why allow top-level pull/issue at all? To make the format simpler for the 95% case.

olivergondza · 2017-02-16T12:07:01Z

I wanted an actual data format here, without it concerned about the (vast majority) of semantically useless URLs...

Alright, I do not feel strongly here.

The major challenge here is moving the content over. If I somehow manage to show output for a combined new YML changelogs / old HTML changelogs output, this should be trivial. If we need to convert everything before switching over, this is going to be more difficult.

I always hated to write in the old format so getting rid of it for new weekly releases as well seems worthy. There is no need to complicate things too much transcribing the old changelogs. How about hardcode the old entries as HTML into page so new releases would be generated and old ones will be presented as written? We can hurry the outdated changelog entries archiving too in case it will cause problems or look strange.

daniel-beck · 2017-02-16T12:43:56Z

@olivergondza

How about hardcode the old entries as HTML into page so new releases would be generated and old ones will be presented as written? We can hurry the outdated changelog entries archiving too in case it will cause problems or look strange.

That's what I meant when I wrote combined … output. I'll look into this.

daniel-beck · 2017-02-16T13:51:54Z

@oleg-nenashev @olivergondza The current state of this PR is 2.32.x in YAML, older changelogs kept as HTML. For me locally, I see no difference in output between the live site and mine (except that the security advisory link itself is also bold now…). This could be merged as is, but would of course result in a disparity between weekly and LTS changelogs.

Please note that format to changelog.html in jenkinsci/jenkins need @kohsuke to adapt his script, unless we just retire that file (importing old content into the site) and write to changelog.yml instead. Then, the changelog update script run as part of the release just writes to an unused file and can be removed or adapted.

olivergondza · 2017-02-17T09:54:45Z

Please note that format to changelog.html in jenkinsci/jenkins need @kohsuke to adapt his script, unless we just retire that file (importing old content into the site) and write to changelog.yml instead. Then, the changelog update script run as part of the release just writes to an unused file and can be removed or adapted.

Is it just marking the trunk changes as released and adding the empty trunk section? In case that is all retiring sounds quite possible to me.

oleg-nenashev · 2017-02-17T09:57:09Z

I think it is important to move both changelogs at once to simplify the maintenance.

Is it just marking the trunk changes as released and adding the empty trunk section? In case that is all retiring sounds quite possible to me.

+1. We do not really need that logic

daniel-beck · 2017-02-17T11:24:51Z

@oleg-nenashev @olivergondza I'd be happy to do both at once, but I need to know the following:

Where do we want changelog.yml to be located?

changelog.html's content will move here, it's an archive of sorts -- like changelog-stable.html after this PR. A skeleton changelog.html will remain in jenkinsci/jenkins for a bit, to not break the release scripts until they can be adapted.

But changelog.yml?

For the following reasons I strongly recommend we put it here:

We discourage changelog contributions in PRs anyway
It simplifies the site build (fewer external crazy to fetch)
A malformed changelog.yml will badly mess up the site build, when it didn't care about changelog.html contents at all, so changes need to go through PR builds

olivergondza · 2017-02-17T14:03:46Z

@daniel-beck, agree with that. AFAICT, stable changelog is hosted in jenkins-infra/jenkins.io solely for a long time (changlog.html exists in stable branches but noone touch it).

I have a good experience with automation generating changelog to be tweaked a bit by human before publishing. I guess we can do something similar, extract all issues/PRs and put it in the yaml and submit PR. Then we will review/adjust where needed and merge.

daniel-beck · 2017-02-17T16:11:55Z

Do we need to get further community input for this decision, or can we implement this and just announce?

FWIW since 2.0 in April last year (the current changelog.html), out of ~350 changes, around ~20 were not authored by Oleg or me based on some creative grepping of git blame output. So to me this looks like a "those who do get to decide" kind of situation.

rtyler · 2017-02-17T18:19:36Z

@daniel-beck I think the three people involved in this PR are the three primary contributors to the changelogs and I doubt anybody will mind having a better way of managing this 😄

I say go for it!

daniel-beck · 2017-02-17T18:59:13Z

@oleg-nenashev @olivergondza I migrated the weekly changelog in #666. Approve and we can get this done this weekend!

oleg-nenashev

Looks good to me. Definitely it's better than HTML

oleg-nenashev · 2017-02-18T00:40:56Z

content/_partials/changes.html.haml

+        - else
+          ,&nbsp;
+        - if reference.issue
+          %a{:href => "https://issues.jenkins-ci.org/browse/JENKINS-#{reference.issue}" }<>


The logic here should ideally check a custom prefix (e.g. "SECURITY"), but not required right now

We don't have separate changelog entries for security vulnerabilities (instead we link to the advisory), and the rare references elsewhere can be done with full URL and label.

daniel-beck · 2017-02-18T01:13:17Z

Closing this in favor of #666

WIP/draft: YAML based LTS changelog

2bb66ae

olivergondza reviewed Feb 16, 2017

View reviewed changes

Switch 2.32.x+ LTS changelog over to YAML

29a9067

daniel-beck changed the title ~~WIP/draft: YAML based LTS changelog~~ YAML based LTS changelog Feb 16, 2017

daniel-beck mentioned this pull request Feb 17, 2017

Migrate weekly changelog and move to YAML #666

Merged

oleg-nenashev approved these changes Feb 18, 2017

View reviewed changes

oleg-nenashev reviewed Feb 18, 2017

View reviewed changes

daniel-beck closed this Feb 18, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

YAML based LTS changelog #661

YAML based LTS changelog #661

daniel-beck commented Feb 16, 2017 •

edited

rtyler commented Feb 16, 2017

olivergondza commented Feb 16, 2017

olivergondza Feb 16, 2017

olivergondza Feb 16, 2017

oleg-nenashev commented Feb 16, 2017 •

edited

oleg-nenashev commented Feb 16, 2017

olivergondza commented Feb 16, 2017

daniel-beck commented Feb 16, 2017

olivergondza commented Feb 16, 2017

daniel-beck commented Feb 16, 2017

daniel-beck commented Feb 16, 2017 •

edited

olivergondza commented Feb 17, 2017

oleg-nenashev commented Feb 17, 2017

daniel-beck commented Feb 17, 2017

olivergondza commented Feb 17, 2017

daniel-beck commented Feb 17, 2017

rtyler commented Feb 17, 2017

daniel-beck commented Feb 17, 2017

oleg-nenashev left a comment

oleg-nenashev Feb 18, 2017

daniel-beck Feb 18, 2017

daniel-beck commented Feb 18, 2017

YAML based LTS changelog #661

YAML based LTS changelog #661

Conversation

daniel-beck commented Feb 16, 2017 • edited

rtyler commented Feb 16, 2017

olivergondza commented Feb 16, 2017

olivergondza Feb 16, 2017

Choose a reason for hiding this comment

olivergondza Feb 16, 2017

Choose a reason for hiding this comment

oleg-nenashev commented Feb 16, 2017 • edited

oleg-nenashev commented Feb 16, 2017

olivergondza commented Feb 16, 2017

daniel-beck commented Feb 16, 2017

olivergondza commented Feb 16, 2017

daniel-beck commented Feb 16, 2017

daniel-beck commented Feb 16, 2017 • edited

olivergondza commented Feb 17, 2017

oleg-nenashev commented Feb 17, 2017

daniel-beck commented Feb 17, 2017

olivergondza commented Feb 17, 2017

daniel-beck commented Feb 17, 2017

rtyler commented Feb 17, 2017

daniel-beck commented Feb 17, 2017

oleg-nenashev left a comment

Choose a reason for hiding this comment

oleg-nenashev Feb 18, 2017

Choose a reason for hiding this comment

daniel-beck Feb 18, 2017

Choose a reason for hiding this comment

daniel-beck commented Feb 18, 2017

daniel-beck commented Feb 16, 2017 •

edited

oleg-nenashev commented Feb 16, 2017 •

edited

daniel-beck commented Feb 16, 2017 •

edited