Proposed Prometheus proposal process.

[bwplotka]

I would love to propose a unified process for proposing design docs in Prometheus. Feel free to discuss and comment on this PR if you have a feedback!

Signed-off-by: bwplotka bwplotka@gmail.com

[GiedriusS]

IMHO this is probably the main pain point. I'm not a maintainer and just someone from the peanut gallery so maybe I'm wrong but I've seen so many good ideas proposed during dev summits but most of them never go anywhere. How to find a sponsor? For example, prometheus/prometheus#3806 is almost 5 years old but there's still no rate() function in upstream Prometheus that doesn't do extrapolation. :/ I am personally interested in this because it's hard to explain to others how come rate() gives this or another result. xrate is much nicer. I even updated the code to work with a newer version of Prometheus but I have no clue how to pursue that further. It would be nice to include something about this.

[bwplotka]

Great point. I think it will be reconsidered if you (or anyone from the community, willing to help in this) would propose it again. I think this proposal process will only help with those problems, don't you think?

There will always be contentious ideas and proposals, but I think Prometheus acknowledged within last year that we need to be more permissive with new ideas, thus my proposal (:

[beorn7]

I think we should primarily focus on solving the typical problems that happen when a change or a new feature is proposed.

The typical fate of an idea discussed at a dev summit is the following:

• Generally, the idea is liked and looks promising.
• The dev summit decides that a design doc is needed.
• More discussions will happen once a design doc exists.
• Nobody steps up to write the design doc.

There is actually no problem with not being permissive enough. The problem is that nobody is doing the work of writing the design doc. The proposal process here intends to unify and facilitate the creation of design docs, and that might actually help with the typical fate described above.

While the project had gained a reputation of "saying no" in the past, I think it has become much more open to change in recent years. There are IMHO very few proposed changes that have ended up in a controversial rejection. Most are indeed in the limbo described above: More research needed, but nobody steps up to do it.

The discussion around rate is a notable exception here, but I think it's structurally so different that it shouldn't be the prime target for the unified proposal process. In contrast to most other proposals, it has actually seen a lot of discussion. A design doc already exists. The problem here is not that the discussion is ignored by the Prometheus maintainers (even if it might appear that way from the outside), the problem is that not a single one is convinced enough about the benefits to champion it. I should also note that the existing implementation is already based on long discussions and extensive research, which is again rather special, as most other proposals are either about a completely new feature or at least intend to change something that is less well explored and established.

[beorn7]

Generally looks great.

It needs wordsmithing, but we can do so once we all agree on the general direction.

You could run a grammar checker over the text, though… ;)

[beorn7]

I think we should primarily focus on solving the typical problems that happen when a change or a new feature is proposed.

The typical fate of an idea discussed at a dev summit is the following:

• Generally, the idea is liked and looks promising.
• The dev summit decides that a design doc is needed.
• More discussions will happen once a design doc exists.
• Nobody steps up to write the design doc.

There is actually no problem with not being permissive enough. The problem is that nobody is doing the work of writing the design doc. The proposal process here intends to unify and facilitate the creation of design docs, and that might actually help with the typical fate described above.

While the project had gained a reputation of "saying no" in the past, I think it has become much more open to change in recent years. There are IMHO very few proposed changes that have ended up in a controversial rejection. Most are indeed in the limbo described above: More research needed, but nobody steps up to do it.

The discussion around rate is a notable exception here, but I think it's structurally so different that it shouldn't be the prime target for the unified proposal process. In contrast to most other proposals, it has actually seen a lot of discussion. A design doc already exists. The problem here is not that the discussion is ignored by the Prometheus maintainers (even if it might appear that way from the outside), the problem is that not a single one is convinced enough about the benefits to champion it. I should also note that the existing implementation is already based on long discussions and extensive research, which is again rather special, as most other proposals are either about a completely new feature or at least intend to change something that is less well explored and established.

[bwplotka]

I will run Grammarly for it, sorry.

EDIT: Done

One cons of markdown is that there is no Grammarly plugin for my Goland editor ;p

[matthiasr]

One thing I am not sure about is placing all the proposals in the top-level directory. This will be very hard to change without breaking all the links. It might become cluttered in two ways – it will be hard to see what else is going on in the repository (configuration, README, check scripts …), while at the same time all these things will clutter the list of proposals. It will also require some exceptions and heuristics in the check process to make sure we are checking the proposals and not, say, the README or license.

What do you think about moving the proposals to a subdirectory? That way, both humans and automated processes can be sure that everything in that directory is a proposal.

[matthiasr]

As a first step, we can make issues to "migrate Proposal X" with a link to the existing one. That way we can represent them quickly in the new place, without blocking on reformatting and/or the owner to pick it up.

[bwplotka]

Thanks @matthiasr - we can consider some proposals directories indeed. Wanted to limit the complexity of this repo. I want to avoid the situation of https://github.com/openshift/enhancements/ where it's quite hard to discover any proposal because it's buried under multiple dirs.

The heuristic is quite simple too: Date as prefix & markdown fil

Not a strong opinion though, we can move to proposals directory if there are no objections from others. Maybe that's indeed cleaner for both humans and automation.

[bwplotka]

There was consensus, so I will proceed with this AFTER adding proposal directory as @matthiasr and Julien mentioned (: