[
https://issues.apache.org/jira/browse/CASSANDRA-17292?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17495629#comment-17495629
]
Paulo Motta edited comment on CASSANDRA-17292 at 2/21/22, 4:51 PM:
-------------------------------------------------------------------
I took a look at the proposed layout and while I think this is a great
improvement from status quo I think that the intermingling of
feature/subsystem/resource in the yaml structure can get a little
counterintuitive and does not provide a consistent framework for extending the
properties. Furthermore the too-many-levels nesting can get tricky pretty fast.
Why do we have to encode the subsystem/resource information in the YAML
hierarchy? I think we can achieve a similar effect of improving discoverability
by grouping co-related properties in different files and subsections within the
same file.
I created an alternative proposal [on this
gist|https://gist.github.com/pauloricardomg/e9e23feea1b172b4f084cb01d7a89b05]
that groups properties in two dimensions: category/feature group.
The category axis is represented by the name of the property filename
("core.yaml", "guardrails.yaml", "features.yaml") and the feature group is
represented by a comment header separating distinct feature groups within the
same category.
One initial example of categories [from the
gist|https://gist.github.com/pauloricardomg/e9e23feea1b172b4f084cb01d7a89b05]
would be:
*
[core.yaml|https://gist.github.com/pauloricardomg/e9e23feea1b172b4f084cb01d7a89b05#file-core-yaml]:
core DB parameters
*
[guardrails.yaml|https://gist.github.com/pauloricardomg/e9e23feea1b172b4f084cb01d7a89b05#file-guardrails-yaml]:
any fail/warn thresholds
*
[features.yaml|https://gist.github.com/pauloricardomg/e9e23feea1b172b4f084cb01d7a89b05#file-features-yaml]:
any (experimental/prod-ready) feature that can be enabled/disabled.
For instance adding new features is basically adding a new section to
[features.yaml|https://gist.github.com/pauloricardomg/e9e23feea1b172b4f084cb01d7a89b05#file-features-yaml].
This layout facilitates extracting subsections to a new file if the number of
properties of that particular section grows too big. For instance, we could
extract the {{encryption}} section of
[core.yaml|https://gist.github.com/pauloricardomg/e9e23feea1b172b4f084cb01d7a89b05#file-core-yaml]
into a new file {{encryption.yaml}} if the need for more specialization
arises. Other macro-categories that we can have if necessary:
* {{{}repair.yaml{}}}: all things repair
* {{{}network.yaml{}}}: all things network
What do you guys think of this alternative? The proposed gist is by far a
complete example, it's just an initial draft to get a feel of how it would look
like.
was (Author: paulo):
I took a look at the proposed layout and while I think this is a great
improvement from status quo I think that the intermingling of
feature/subsystem/resource in the yaml structure can get a little
counterintuitive and does not provide a consistent framework for extending the
properties. Furthermore the too-many-levels nesting can get tricky pretty fast.
Why do we have to encode the subsystem/resource information in the YAML
hierarchy? I think we can achieve a similar effect of improving discoverability
by grouping co-related properties in different files and subsections within the
same file.
I created an alternative proposal [on this
gist|https://gist.github.com/pauloricardomg/e9e23feea1b172b4f084cb01d7a89b05]
that groups properties in two dimensions: category/feature group.
The category axis is represented by the name of the property filename
("core.yaml", "guardrails.yaml", "features.yaml") and the feature group is
represented by a comment header separating distinct feature groups within the
same category.
One initial example of categories [from the
gist|https://gist.github.com/pauloricardomg/e9e23feea1b172b4f084cb01d7a89b05]
would be:
* {{{}core.yaml{}}}: core DB parameters
* {{{}guardrails.yaml{}}}: any fail/warn thresholds
* {{{}features.yaml{}}}: any (experimental/prod-ready) feature that can be
enabled/disabled.
For instance adding new features is basically adding a new section to
{{{}features.yaml{}}}.
This layout facilitates extracting subsections to a new file if the number of
properties of that particular section grows too big. For instance, we could
extract the {{encryption}} section of {{core.yaml}} into a new file
{{encryption.yaml}} if the need for more specialization arises. Other
macro-categories that we can have if necessary:
* {{{}repair.yaml{}}}: all things repair
* {{{}network.yaml{}}}: all things network
What do you guys think of this alternative? The proposed gist is by far a
complete example, it's just an initial draft to get a feel of how it would look
like.
> Move cassandra.yaml toward a nested structure around major database concepts
> ----------------------------------------------------------------------------
>
> Key: CASSANDRA-17292
> URL: https://issues.apache.org/jira/browse/CASSANDRA-17292
> Project: Cassandra
> Issue Type: Improvement
> Components: Local/Config
> Reporter: Caleb Rackliffe
> Assignee: Caleb Rackliffe
> Priority: Normal
> Fix For: 5.x
>
>
> Recent mailing list conversation (see "[DISCUSS] Nested YAML configs for new
> features") has made it clear we will gravitate toward appropriately nested
> structures for new parameters in {{cassandra.yaml}}, but from the scattered
> conversation across a few Guardrails tickets (see CASSANDRA-17212 and
> CASSANDRA-17148) and CASSANDRA-15234, there is also a general desire to
> eventually extend this to the rest of {{cassandra.yaml}}. The benefits of
> this change include those we gain by doing it for new features (single point
> of interest for feature documentation, typed configuration objects, logical
> grouping for additional parameters added over time, discoverability, etc.),
> but one a larger scale.
> This may overlap with ongoing work, including the Guardrails epic. Ideally,
> even a rough cut of a design here would allow that to move forward in a
> timely and coherent manner (with less long-term refactoring pain).
> While these would have to be adjusted to CASSANDRA-15234 (probably after it
> merges), there have been two proposals floated already for what this might
> look like:
> From [~maedhroz] -
> https://github.com/maedhroz/cassandra/commit/450b920e0ac072cec635e0ebcb63538ee7f1fc5a
> From [~benedict] -
> https://github.com/belliottsmith/cassandra/commits/CASSANDRA-15234-grouping-ideas
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
