(draft) conf: GENERIC: Add a disclaimer on customized kernel configurations

[olce]

Summary

Some disclaimer proposal to add to GENERIC (done only to amd64's versions here, to be then duplicated in all GENERICs).

What about MINIMAL?

If going into this direction, this Handbook's page (https://docs.freebsd.org/en/books/handbook/kernelconfig/) would have to be revised to match the tone.

[thj]

Tweak some wording to imply reality

I am not sure if we as a community want to be this direct/aggressive. I worry that we have gone so long being accommodating that a warning like this is too much.

sys/amd64/conf/GENERIC

25

26

[kp]

In D46870#1068713, @thj wrote:

I am not sure if we as a community want to be this direct/aggressive. I worry that we have gone so long being accommodating that a warning like this is too much.

Perhaps we should try to phrase it as a positive. Something like

# WARNING: GENERIC is intended to be suitable for all users, and is the most tested configuration. It's best to not deviate from it unless there is genuinely no alternative.

[olce]

In D46870#1068713, @thj wrote:

I am not sure if we as a community want to be this direct/aggressive. I worry that we have gone so long being accommodating that a warning like this is too much.

IMO, direct is good. Aggressive, of course, is not. I didn't perceive it like that at first, but going to rephrase a bit the "rough edges".

In D46870#1068716, @kp wrote:

Perhaps we should try to phrase it as a positive. Something like

# WARNING: GENERIC is intended to be suitable for all users, and is the most tested configuration. It's best to not deviate from it unless there is genuinely no alternative.

That's great as the first line, but I think it could be valuable to keep explicit the part detailing which concrete drawbacks and costs deviating from GENERIC could entail, re-phrasing it as necessary so that it doesn't look too negative.

[olce]

Tweak as suggested, re-phrase parts to avoid sounding aggressive.

[olce]

The current stance may be too sharp for GENERIC, especially in relation with all the device drivers. Waiting for others' input and if I can find some better idea.

[imp]

I hate it.
This is way too long, and too paternalistic.
And completely unnecessary.
The vast majority of custom kernels just remove drivers, which is completely safe (either it works or it doesn't and people removing them are smart enough to cope judging from our support questions).
This is a complete over-reaction to the INET* fracus, which is itself an over-reaction to kp@'s off hand comments that just state that we're imperfect at supporting it for every single commit and there may be test coverage issues (which may or may not matter, more likely with INET* than omitting the ciss driver, but it's hard to convey that nuance).

[olce]

In D46870#1068856, @imp wrote:

This is way too long, and too paternalistic.

That can be rephrased. But I think it is important that we say which level of support we are providing to users and what we expect from them in the case of custom kernels. The targets are not members of the project, but rather outsiders.

And completely unnecessary.

I disagree. And part of the reason is simply D46875. If it makes you more comfortable, we could instead use some text closer to what was added to the handbook in D46875.

My point is that there needs to be a text in GENERIC (and perhaps NOTES) in addition to the handbook's, because it is likely that people already tweaking kernels or coming from other systems will never read the corresponding part of the handbook but rather man pages.

The vast majority of custom kernels just remove drivers, which is completely safe (either it works or it doesn't and people removing them are smart enough to cope judging from our support questions).

We can add a sentence to say that removing device drivers is generally safe (if not going so far as to break ability to boot).

This is a complete over-reaction to the INET* fracus, which is itself an over-reaction to kp@'s off hand comments that just state that we're imperfect at supporting it for every single commit and there may be test coverage issues (which may or may not matter, more likely with INET* than omitting the ciss driver, but it's hard to convey that nuance).

I don't think that better communication to outsiders is an over-reaction. Also, beyond the text proposed here, a clarification over what level of support users can expect would be welcome. E.g., do we offer compile guarantee for the sources of a release, and for which configurations?

[imp]

Respectfully, this is an over-reaction.

We've not needed it for 30-odd years. Why the sudden need for an overly long, overly paternalistic, needlessly verbose message.

At most, and I don't even think we need this, we my need

# Rather than copying and editing GENERIC, just include GENERIC and
# use nooption and nodevice to remove unwanted options.

maybe with a third line

# Non-standard configurations get no testing and are at the risk of the user

We really need an options(9) that documents all our options, the risks and pitfalls, if
any, with each. Some vague, nebulous, but also verbose message isn't an effective
way to communicate.

[olce]

In D46870#1068885, @imp wrote:

Respectfully, this is an over-reaction.

Well, that could rather be said of your first comment.

I've just explained my goals in the previous comment, but your response gives no indication that you've actually read and understood them. Without that, it's going to be hard to discuss further, and that also makes "respectfully" resonate strangely to my ears.

We've not needed it for 30-odd years. Why the sudden need for an overly long, overly paternalistic, needlessly verbose message.

Because it seems that some developers are from time to time annoyed by people trying to do custom builds that fail. And I'm mostly just a messenger here, not even directly concerned for now.

Why not try to fix that once and for all? At least, providing some text that gets more chances to be discovered without our intervention?

Do you find instructions of expected behavior when interacting with a project paternalistic? I see that as actually positive. Again, the targets are outsiders, and more precisely people that don't necessarily have a clue on how to interact with a project like ours. From this point of view, it isn't that verbose though, and still can be trimmed down/re-phrased a bit. But if it facilitates things, I'm OK with instead copying the new handbook's text here, possibly amending it a bit with project expectations.

At most, and I don't even think we need this, we my need

# Rather than copying and editing GENERIC, just include GENERIC and
# use nooption and nodevice to remove unwanted options.

A good idea in its own right, but that has nothing to do with the current discussion.

maybe with a third line

# Non-standard configurations get no testing and are at the risk of the user

For the goals I wrote above, that's clearly not enough (which configs are standard? what if they start bothering with a bug that doesn't exist with GENERIC? etc.).

But maybe you disagree with the goals, and that's fine.

We really need an options(9) that documents all our options, the risks and pitfalls, if
any, with each.

That would be great.

Some vague, nebulous, but also verbose message isn't an effective way to communicate.

I disagree again. You really don't seem to understand the goals. And the message is far from being vague or nebulous, it is rather general. It lists breakage/problems users could experience and which efforts custom kernels may require from them, *in general*.

It is probably too strong in its current form, but nothing prevents us from amending it.

More importantly, I think it's better to add some sensible, general text on the topic to GENERIC and NOTES, even if imperfect, rather than waiting for options(9) to materialize (which anyway probably should contain the exact same general message in its introduction).

[imp]

Again, the config files is *NOT* the place for this information.. I will die on this hill. It does not accomplish the goals and does make it a pain to update the config files.

Also, you forgot MINIMAL, and all the other architectures, etc.

And NOTES isn't used as a production config, so I'm not sure the warning is good there..

Why? Because we have to copy it 20 times to all the config file we have for all the architectures. People using tier 1 aarch64 won't see them, for example, since you forgot about it.

Caveats like this belong in a man page. Put the warnings in config(8), not in a zillion copies in all the config files. Or better yet, write options(9) so we can add specific warnings about specific options there.

[olce]

In D46870#1068976, @imp wrote:

Again, the config files is *NOT* the place for this information.

I think I explained enough why it is probably a good one, in addition to others. I'm still waiting for your arguments.

I will die on this hill.

Nobody has to die. But this is a good illustration of "over-reaction".

It does not accomplish the goals and does make it a pain to update the config files.

It does accomplish the goal for people jumping right to kernel config files and reading the preamble there. If they don't read the preamble, well, we're screwed anyway. Speaking about goals, it seems there is a misunderstanding. I'm talking about the ones I've already exposed. What are yours exactly?

Which pain are you talking about? I'm just proposing a general statement, with probably pointers to other things (such as options(9) or whatever) in the future. This needs no more updating than the rest of the preamble (e.g., "The handbook is also available locally in (...)").

Also, you forgot MINIMAL, and all the other architectures, etc.

A proof that you didn't read what I wrote. Would you please read for me the text under this revision's SUMMARY, at the top of the page?

And NOTES isn't used as a production config, so I'm not sure the warning is good there..

Some guys could read NOTES as a kind of more detailed reference than GENERIC is. It don't think it hurts to copy the text there too, even if I share your doubt here.

Why? Because we have to copy it 20 times to all the config file we have for all the architectures.

And? The current preamble is already copied 20 times.

People using tier 1 aarch64 won't see them, for example, since you forgot about it.

I haven't. Additionally, I fail to see how this could have a bearing on this discussion.

Caveats like this belong in a man page. Put the warnings in config(8), not in a zillion copies in all the config files. Or better yet, write options(9) so we can add specific warnings about specific options there.

I support putting them in a man page, but this doesn't rule out putting them in GENERIC.

Given the current build(7) state, which doesn't mention config(8) a single time except in the SEE ALSO section, putting it in config(8) is probably not a good idea as this man page is not easy to discover.

I'm probably not the best person to write options(9). If nobody does, I may try at some point, but in truth this is very far for being my main priority. In any case, at the risk of repeating myself:

More importantly, I think it's better to add some sensible, general text on the topic to GENERIC and NOTES, even if imperfect, rather than waiting for options(9) to materialize (which anyway probably should contain the exact same general message in its introduction).

[imp]

My argument against in the config file is multiple copies of long messages is unmaintainable and we'veshown this many timesin the past. Also, info like this needs to be in a man page. Config.8 is the right place, though there were efforts to create GENERIC.9 etc. I'll have to see if i can find them. Comments in a config file are the last place that info goes and only until it can be put in the more accessible place.

I'll push my propsed alertnative so it's clear what I am proposing instead .

[olce]

Add just a small disclaimer for now.

To be extended (later) with something like "Please consult config(8)/GENERIC(9) for more information.".

[olce]

In D46870#1068995, @imp wrote:

My argument against in the config file is multiple copies of long messages is unmaintainable and we'veshown this many timesin the past.

I've reduced the text. This is only a single sentence that, again, doesn't need to change. I don't know what other experiences you're referring too, but aren't they quite different?

Also, info like this needs to be in a man page. Config.8 is the right place, though there were efforts to create GENERIC.9 etc. I'll have to see if i can find them. Comments in a config file are the last place that info goes and only until it can be put in the more accessible place.

I agree. And to clarify what I said above, I don't deny that config(8) is the most logical place currently (GENERIC(9) would probably be better). However, as I've already explained, config(8) is especially hard to discover, so there needs to be pointers to it (in GENERIC, in UPDATING, etc.).

I'll push my propsed alertnative so it's clear what I am proposing instead .

Let's see what you come up with. However, I don't think this should hold back adding the disclaimer.