Add DeprecatedVersion to struct FamilyGenerator and func NewFamilyGenerator

[YuikoTakada]

What this PR does / why we need it:

Currently, in kube-state-metrics, deprecated metrics is managed just in document. And also there are many docs about metrics(node-metrics.md, pod-metrics.md, ...)
This PR adds a new field "DeprecatedVersion" to struct FamilyGenerator and new func "NewFamilyGenerator" which generate struct FamilyGenerator. In NewFamilyGenerator, if the metrics is deprecated, "(Deprecated since x.x)" will be added at the begining of help string. It makes easier to manage deprecated metrics.

Also see:
https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/component-base/metrics/opts.go#L198

type SummaryOpts struct {
	Namespace         string
	Subsystem         string
	Name              string
	Help              string
	ConstLabels       map[string]string
	Objectives        map[float64]float64
	MaxAge            time.Duration
	AgeBuckets        uint32
	BufCap            uint32
	DeprecatedVersion string <---
	deprecateOnce     sync.Once
	annotateOnce      sync.Once
	StabilityLevel    StabilityLevel
}

Which issue(s) this PR fixes (optional, in fixes #<issue number>(, fixes #<issue_number>, ...) format, will close the issue(s) when PR gets merged):
Fixes #

[brancz]

I like this a lot! Similar to the metrics stability framework, could you add that the description is prefixed with the deprecated version?

[YuikoTakada]

@brancz Thank you for your comments. Sorry I don't understand what you say. You mean DeprecatedVersion will be set like "DeprecatedVersion: 1.19"? It would be written as just "1.19". I'm sorry if I misunderstand what you say.

[brancz]

In Kubernetes, when a metric is deprecated, it will say in the help text for example:

kube_pod_info (Deprecated since 1.19)

I would like that we also do this in kube-state-metrics.

[YuikoTakada]

@brancz Thanks, I understand. In kubernetes, in case of kube-scheduler, the string "Deprecated since x.xx.x" in #HELP is written manually like https://github.com/kubernetes/kubernetes/pull/92160/files (This is my PR, approved but not merged yet😅)

[brancz]

In kubernetes/kubernetes a metric is annotated with it's deprecated version (if it's deprecated), and since which version. https://github.com/kubernetes/component-base/blob/d18546f5347cab6a8690e9b863d9ab977f771079/metrics/desc.go#L196

[YuikoTakada]

@brancz oh, I didn't know it. Thank you for the advice. I will try to fix this PR.

[YuikoTakada]

I've added new func NewFamilyGenerator also. If it looks good, I will fix all callers of FamilyGenerator to use NewFamilyGenerator. Thanks.

[brancz]

The strategy looks good, but there are some failures that need fixing.

[lilic]

Seems like the failures is:

ERRO Running error: golint: analysis skipped: errors in package: [/home/travis/gopath/src/k8s.io/kube-state-metrics/pkg/metric_generator/generator.go:47:35: undeclared name: obj /home/travis/gopath/src/k8s.io/kube-state-metrics/pkg/metric_generator/generator.go:47:22: cannot use generateFunc(obj) (value of type *metric.Family) as func(obj interface{}) *metric.Family value in struct literal] 

[brancz]

/lgtm

Leaving approval up to @tariq1890 or @lilic

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: brancz, YuikoTakada

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [brancz]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[brancz]

sorry I didn't realize that it would also automatically approve the PR. @tariq1890 @lilic please feel free to comment anyways! :)