Cut v1.2.0 #2059

beorn7 · 2016-10-06T19:32:24Z

It's about time.

@brian-brazil @fabxc @juliusv @grobie all good? Anything else that has to go in?

juliusv · 2016-10-06T19:43:55Z

CHANGELOG.md

+* [FEATURE] Enable the use of query parameters in `/graph` URLs.
+* [FEATURE] PromQL: Add `minute()` function.
+* [FEATURE] Add GCE service discovery.
+* [FEATURE] Allow job names to start with a digit.


IIRC we actually changed that PR to allow arbitrary job names now.

Yes. I'd write "Allow all valid label values as job names in config files."

juliusv · 2016-10-06T19:45:08Z

CHANGELOG.md

@@ -1,3 +1,43 @@
+## 1.2.0 / 2016-10-07
+
+* [FEATURE] Enable the use of query parameters in `/graph` URLs.


Maybe more like "Cleaner encoding of query parameters in /graph URLs" or so?

juliusv · 2016-10-06T19:47:43Z

CHANGELOG.md

+* [FEATURE] Allow disabling local storage.
+* [FEATURE] EC2 service discovery: Expose `ec2_instance_state`.
+* [FEATURE] HTTP basic auth and TLS support for remote write path.
+* [FEATURE] Support for relabelling in remote write path.


Just a heads-up: this and remote write configuration in general aren't documented yet. Remote write in general should be documented as experimental. I filed two issues:

prometheus/docs#582
prometheus/docs#583

I marked those features as belonging to an experimental part of the project.

juliusv · 2016-10-06T19:52:33Z

CHANGELOG.md

+Below changes are not considered breaking because they affect parts marked as
+experimental or unstable:
+
+* [CHANGE] Remote write path does not use gRPC anymore.


Also, the remote write path is now configured via the configuration file, not via a flag anymore.

Still under "experimental" scope, right?

grobie

LGTM

grobie · 2016-10-07T00:53:07Z

CHANGELOG.md

+* [FEATURE] Enable the use of query parameters in `/graph` URLs.
+* [FEATURE] PromQL: Add `minute()` function.
+* [FEATURE] Add GCE service discovery.
+* [FEATURE] Allow job names to start with a digit.


Yes. I'd write "Allow all valid label values as job names in config files."

grobie · 2016-10-07T00:54:38Z

CHANGELOG.md

+* [FEATURE] EC2 service discovery: Expose `ec2_instance_state`.
+* [FEATURE] HTTP basic auth and TLS support for remote write path.
+* [FEATURE] Support for relabelling in remote write path.
+* [ENHANCEMENT] Add `go_import_path` to Travis so it works on a fork.


This is a build internal and I wouldn't mention it here, as it doesn't help me as operator when reviewing a version update changelog.

If you believe it's important to mention such commits, I'd use a different group for such changes and move it to the bottom.

Removed as per general discussion.

grobie · 2016-10-07T00:54:50Z

CHANGELOG.md

+* [FEATURE] HTTP basic auth and TLS support for remote write path.
+* [FEATURE] Support for relabelling in remote write path.
+* [ENHANCEMENT] Add `go_import_path` to Travis so it works on a fork.
+* [ENHANCEMENT] Makefile: Promu installation now logged.


Removed as per general discussion.

fabxc · 2016-10-07T08:38:30Z

CHANGELOG.md

+* [CLEANUP] Export various identifiers for better code reuse.
+* [CLEANUP] Cleanup code issues reported by goreport and added link to
+  goreport in README.md.
+* [CLEANUP] Various other minor code cleanups and fixed typos.


Irrelevant to the user.

Removed as per general discussion.

fabxc

Sorry, this got quite spammy but I recall us having agreed long ago to only list changes that affect operators and users long ago.

This is largely noise to people who want to find out if and why the should upgrade.

fabxc · 2016-10-07T08:38:42Z

CHANGELOG.md

+* [CLEANUP] Consolidate web API contexts. Update `common/route` vendoring.
+* [CLEANUP] Storage: Chunk code in own package. Added Utilization method.
+* [CLEANUP] Export various identifiers for better code reuse.
+* [CLEANUP] Cleanup code issues reported by goreport and added link to


Irrelevant to the user.

Removed as per general discussion.

fabxc · 2016-10-07T08:39:23Z

CHANGELOG.md

+* [CLEANUP] Add contexts to PromQL and storage interfaces.
+* [CLEANUP] Consolidate web API contexts. Update `common/route` vendoring.
+* [CLEANUP] Storage: Chunk code in own package. Added Utilization method.
+* [CLEANUP] Export various identifiers for better code reuse.


Irrelevant to the user. Only package users might be interested, who are not tied to the versioning scheme of the binary releases.

Removed as per general discussion.

fabxc · 2016-10-07T08:39:40Z

CHANGELOG.md

+* [CLEANUP] More tests for PromQL time functions.
+* [CLEANUP] Add contexts to PromQL and storage interfaces.
+* [CLEANUP] Consolidate web API contexts. Update `common/route` vendoring.
+* [CLEANUP] Storage: Chunk code in own package. Added Utilization method.


Irrelevant to the user. Only package users might be interested, who are not tied to the versioning scheme of the binary releases.

Removed as per general discussion.

fabxc · 2016-10-07T08:39:48Z

CHANGELOG.md

+* [CLEANUP] Remove DNS resolution dependency from tests.
+* [CLEANUP] More tests for PromQL time functions.
+* [CLEANUP] Add contexts to PromQL and storage interfaces.
+* [CLEANUP] Consolidate web API contexts. Update `common/route` vendoring.


Irrelevant to the user.

Removed as per general discussion.

fabxc · 2016-10-07T08:39:52Z

CHANGELOG.md

+* [BUGFIX] Handle NaN in `changes()` correctly.
+* [CLEANUP] Remove DNS resolution dependency from tests.
+* [CLEANUP] More tests for PromQL time functions.
+* [CLEANUP] Add contexts to PromQL and storage interfaces.


Irrelevant to the user.

Removed as per general discussion.

fabxc · 2016-10-07T08:39:58Z

CHANGELOG.md

+  is down.
+* [BUGFIX] Handle NaN in `changes()` correctly.
+* [CLEANUP] Remove DNS resolution dependency from tests.
+* [CLEANUP] More tests for PromQL time functions.


Irrelevant to the user.

Removed as per general discussion.

fabxc · 2016-10-07T08:40:05Z

CHANGELOG.md

+* [BUGFIX] Do not fail Consul discovery on Prometheus startup when Consul
+  is down.
+* [BUGFIX] Handle NaN in `changes()` correctly.
+* [CLEANUP] Remove DNS resolution dependency from tests.


Irrelevant to the user.

Removed as per general discussion.

fabxc · 2016-10-07T08:40:49Z

CHANGELOG.md

+* [FEATURE] Support for relabelling in remote write path.
+* [ENHANCEMENT] Add `go_import_path` to Travis so it works on a fork.
+* [ENHANCEMENT] Makefile: Promu installation now logged.
+* [ENHANCEMENT] Fingerprint locking: Avoid having contended mutexes on


Very implementation specific. Not every user will understand what this means for them in practice.

Removed as per general discussion.

fabxc · 2016-10-07T08:41:39Z

CHANGELOG.md

+* [ENHANCEMENT] Makefile: Promu installation now logged.
+* [ENHANCEMENT] Fingerprint locking: Avoid having contended mutexes on
+  same cacheline.
+* [ENHANCEMENT] Avoid slow `defer` in the `seriesMap.get` hot spot.


Very implementation specific. Not every user will understand what this means for them in practice.
Possibly consolidate the performance improvements into a single understandable entry.

Consolidated into "Various performance improvements in local storage."

fabxc · 2016-10-07T08:42:39Z

CHANGELOG.md

+* [BUGFIX] Zookeeper service discovery: Remove deleted nodes.
+* [BUGFIX] Zookeeper service discovery: Resync state after Zookeeper failure.
+* [BUGFIX] Remove JSON from HTTP Accept header.
+* [BUGFIX] Update govalidator vendoring to fix URL validation.


For the user this means fixed Alertmanager URL flags, which is not clear.

beorn7 · 2016-10-07T08:54:26Z

Sorry, this got quite spammy but I recall us having agreed long ago to only list changes that affect operators and users long ago.

I do not recall anything like that. I (strongly) think the changelog should document all changes, for all audiences (operators, builders, developers, users, …). Obviously, I wouldn't document "added a period at the end of doc comment", in those cases we should make the call and just summarize it as "various code cleanups", as I have done here.

As usual, I'm willing to bend to a majority decision of qualified people. Before changing anything in this PR, could we have a quick straw poll what the target audience of the changelog should be? @fabxc and myself have already cast their vote. @grobie seems to be on the same train as @fabxc (which would hint towards the existence of such an undocumented agreement). (Although I have to say that the comment @grobie was referring to is actually relevant to operators, should said operators maintain a fork of Prometheus, which might be common in larger organizations that audit code and build their own binaries from it.)

brian-brazil · 2016-10-07T08:57:23Z

Changelog should be aimed primarily at users. If someone wants a blog by blow they can look at the commit history.

My blog being the only usable source of user-relevant changelog info would not be good for the project IMHO.

fabxc · 2016-10-07T09:32:44Z

I'm confident anyone maintaining an internal fork and audits changes will not trust a changelog regardless of its verbosity. They also know how to run git log --oneline --no-merges, which is the only relevant change log for developers.

Yes, it does include a few commits adding periods to doc comments or whatnot – those are a pollution of history and waste of everyone's time in the first place. (Dozens of people are emailed about it, and at least 5 of them are taking action on each of them.)

grobie · 2016-10-07T09:39:31Z

As someone who has to regularly review and apply updates of software, I
feel strongly about only documenting user relevant changes like behaviour+
performance changes, features and bug fixes.

Changes to internal code structure, test setup, build infrastructure, etc.
are only relevant to the very small subset of active regular contributors
of which we have maybe 10 people. I disagree that the line I commented
about is relevant to the average operator. So far the only reported use
case was for the single active public fork we have.

The small active developer audience continuously being interested in such
other changes and not already following the development can use git diff.

On Fri, Oct 7, 2016, 10:57 Brian Brazil notifications@github.com wrote:

Changelog should be aimed primarily at users. If someone wants a blog by
blow they can look at the commit history.

My blog being the only usable source of user-relevant changelog info would
not be good for the project IMHO.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#2059 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAANaO4rDj0_qpIjQ21XymfQ3_ew8ZWOks5qxgl0gaJpZM4KQU-3
.

beorn7 · 2016-10-07T11:01:33Z

Thanks for casting your votes. I think we have quorum. I'll update the documentation and this PR accordingly.

It now follows the policy of only documenting user-relevant changes.

beorn7 · 2016-10-07T11:42:16Z

CHANGELOG abbreviated according to new guideline and all other comments addressed.

I also removed again the separate CHANGES section for experimental features. The intention was to not have a big and fat breaking change on top of the list (for a minor release). Now I have grouped all changes to the remote write path at the bottom of the list and marked them cleary as experimental so people don't get scared about the breaking changes.

grobie

Thanks. LGTM

beorn7 · 2016-10-07T12:43:06Z

Thanks everybody. Now working on the remaining steps for the release.

Cut v1.2.0

836c61e

juliusv reviewed Oct 6, 2016

View reviewed changes

grobie reviewed Oct 7, 2016

View reviewed changes

fabxc reviewed Oct 7, 2016

View reviewed changes

fabxc suggested changes Oct 7, 2016

View reviewed changes

Abbreviate CHANGELOG.md entry for 1.2.0

d8cbac1

It now follows the policy of only documenting user-relevant changes.

fabxc approved these changes Oct 7, 2016

View reviewed changes

grobie approved these changes Oct 7, 2016

View reviewed changes

Merge branch 'master' into release-1.2

522c933

beorn7 merged commit 0cf8586 into master Oct 7, 2016

beorn7 deleted the release-1.2 branch October 7, 2016 12:42

beorn7 restored the release-1.2 branch October 7, 2016 12:53

grobie mentioned this pull request Oct 16, 2016

Prepare for 0.13.0-rc.1 release. prometheus/node_exporter#313

Merged

		@@ -1,3 +1,43 @@
		## 1.2.0 / 2016-10-07

		* [FEATURE] Enable the use of query parameters in `/graph` URLs.

Cut v1.2.0 #2059

Cut v1.2.0 #2059

Conversation

beorn7 commented Oct 6, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

grobie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fabxc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

beorn7 commented Oct 7, 2016

brian-brazil commented Oct 7, 2016

fabxc commented Oct 7, 2016

grobie commented Oct 7, 2016

beorn7 commented Oct 7, 2016

beorn7 commented Oct 7, 2016

grobie left a comment

Choose a reason for hiding this comment

beorn7 commented Oct 7, 2016