rsyslog-doc
rsyslog-doc copied to clipboard
rsyslog
Consider opening up maintenance of the v5-stable branch
@rgerhards
The discussion on rsyslog/rsyslog#2367 brought up an interesting quandry:
- The current project philosophy is to touch the legacy codebase as little as possible (presumably to reduce effort spent on code intended to only provide compatibility while users switch to the
advancedformat configuration and to reduce chances of breaking configs used in prod) - We are actively pruning coverage of the
obsolete legacyconfiguration format from the current master and v8-stable doc branches, so including references to changes in theobsolete legacyconf format is a questionable decision - As previously discussed, the plan was to point users to the v5 docs for coverage of the older format. If that is still the goal, perhaps we should be making changes to that branch to cover inconsistencies in how the legacy code operates?
Refs: https://github.com/rsyslog/rsyslog/pull/2367#issuecomment-356803240 (remarks by @davidelang )
(maintainer hat on): I do not violently object opening up v5-stable for edits, but I would caution against putting too much effort into it. We are short on resources, and I would prefer to see work being done on current doc rather than "the old cruft".
(maintainer head off): I personally have very little interest in doing work on v5 doc. It is bad, but it always has been ;-) Better doc may even make people continue to use it longer than we hope for. A breaking fix of semantics on the old formatis always very questionable. I am not yet sure how the rsyslog PR will end up. I am personally pretty undecided. It's also the first such issue in years...
@rgherhards: (maintainer hat on): I do not violently object opening up v5-stable for edits, but I would caution against putting too much effort into it. We are short on resources, and I would prefer to see work being done on current doc rather than "the old cruft".
I agree. It was more for cases like https://github.com/rsyslog/rsyslog/pull/2367#issuecomment-356803240, assuming that the decision is made to document the discrepancy and not made source code changes to resolve it.
@rgerhards: (maintainer head off): I personally have very little interest in doing work on v5 doc. It is bad, but it always has been ;-) Better doc may even make people continue to use it longer than we hope for.
I can see that, but I can also see that as we clean up the v8-stable docs and remove coverage for the obsolete legacy format that it would be good to make light changes to an authoritative source for the obsolete legacy format until such time that it is completely retired.
@rgerhards: A breaking fix of semantics on the old format is always very questionable. I am not yet sure how the rsyslog PR will end up. I am personally pretty undecided. It's also the first such issue in years...
Understood. I won't attempt any doc edits for that branch until you come to a decision on the PR then.
any currently supported linux distro is using (or at least offering as an option) something much newer than v5. Considering how many years it's been since the last V5 release, any updates to the docs are not going to get to the users (if the distros were updating anything, they would be on a newer version)
At this point, any time spent on v5 docs is wasted IMHO
any currently supported linux distro is using (or at least offering as an option) something much newer than v5. Considering how many years it's been since the last V5 release, any updates to the docs are not going to get to the users (if the distros were updating anything, they would be on a newer version)
At this point, any time spent on v5 docs is wasted IMHO
The idea for updating the v5 docs comes from the idea of pruning all obsolete legacy format coverage from the current master/v8-stable branches and then forwarding the users to the v5-stable docs for coverage of the obsolete legacy coverage. See https://github.com/rsyslog/rsyslog-doc/issues/394#issuecomment-347259269 for earlier discussion on that point.
If the decision is made on rsyslog/rsyslog#2367 that code changes won't be made to fix the issue (which @rgerhards mentioned is still under consideration), but instead doc changes to cover/highlight the discrepancy, then I think we could place that coverage of the discrepancy with the official coverage for the obsolete legacy format.
This is why I mention opening up the v5-stable branch for updates. I do not have plans myself to make heavy edits to the branch, but if the decision is that we are going to prune the obsolete legacy format from current branches, then we need one source to send users to for coverage of the older format. That source would then need at least some minimal maintenance to remain useful as a reference. I see it as more of a "back-port" effort than something ongoing with a significant investment of cleanup effort.
I believe we still have plenty of work to do with the current docs before borrowing work from a historical doc, no worries with me seeing that.
On Mon, 15 Jan 2018, Deoren Moor wrote:
any currently supported linux distro is using (or at least offering as an option) something much newer than v5. Considering how many years it's been since the last V5 release, any updates to the docs are not going to get to the users (if the distros were updating anything, they would be on a newer version)
At this point, any time spent on v5 docs is wasted IMHO
The idea for updating the v5 docs comes from the idea of pruning all obsolete legacy format coverage from the current master/v8-stable branches and then forwarding the users to the v5-stable docs for coverage of the obsolete legacy coverage. See https://github.com/rsyslog/rsyslog-doc/issues/394#issuecomment-347259269 for earlier discussion on that point.
ahh, I disagree with removing all reference to the obsolete legacy parameters, someone looking to figure out what a config they inherited does should not be pointed at a different set of documentation (especially when the config file may have a mix of obsolete and advanced things that won't be in the other documenation)
They should be in a separate section that clearly says "you should not use these for a new config, these are only here to help you understand existing configs"
@davidelang: ahh, I disagree with removing all reference to the obsolete legacy parameters, someone looking to figure out what a config they inherited does should not be pointed at a different set of documentation (especially when the config file may have a mix of obsolete and advanced things that won't be in the other documenation)
In many ways, that is what the present documentation is mostly composed of. I have updated some files to remove obsolete legacy format, but much remains to complete that effort.
They should be in a separate section that clearly says "you should not use these for a new config, these are only here to help you understand existing configs"
Is there any situation where you would see forwarding to a specific doc a reasonable choice? For example, let's say you go to look up the parameters for the imuxsock module and you see a section titled Obsolete Legacy Directives in the Table of Contents. You go there and find a short message noting that it is a deprecated format, is not recommended for new use (and if rsyslog/rsyslog#2383 gets traction) will go away at some point. You then find a link that takes you directly to the v5 imuxsock doc.
On that note, perhaps we fork from v5 and apply some basic cleanup effort to brand it as the sole source of information for obsolete legacy format coverage.
The other option is to keep the old branches static, and make sure every doc has two sections, one for advanced format coverage and another for obsolete legacy format coverage.
If the latter (what we had before), we'll need to restore some of the content previously removed, but it is doable.
@rgerhards Your thoughts?
On Mon, 15 Jan 2018, Deoren Moor wrote:
Is there any situation where you would see forwarding to a specific doc a reasonable choice? For example, let's say you go to look up the parameters for the
imuxsockmodule and you see a section titledObsolete Legacy Directivesin the Table of Contents. You go there and find a short message noting that it is a deprecated format, is not recommended for new use (and if rsyslog/rsyslog#2383 gets traction) will go away at some point. You then find a link that takes you directly to the v5imuxsockdoc.
The problem is that I'm not going to be looking for parameters to the imuxsock module, I will be wondering what $somestrangename means, and if I search the current docs and there is no mention of it, that's a problem.
I'll first be looking through the doc tarball that ships with rsyslog, and if it doesn't appear in any doc shipped with the version I'm running, I won't know to go download a different doc tarball, I'll just assume that the rsyslog docs are junk to not include a parameter that's been in use for a long time.
so either you ship the v5 docs along with the v8 docs, or you need to include all the existing 'obsolete legacy' parameters in the v8 docs.
The other option is to keep the old branches static, and make sure every doc has two sections, one for
advancedformat coverage and another forobsolete legacyformat coverage.
Last I looked (sorry for not paying attention here), I thought we agreed on the need for three sections
Advanced Legacy Obsolete Legacy
Even after we stop supporting Obsolete Legacy parameters, we are going to need to leave them in the docs for a few years (aren't we still getting questions about rsyslog 7.4 because that's what RedHat shipped with and is still listing as 'supported'?), we need to leave things in the docs so that someone who upgrades a distro after it hits the 5+ year End of Life has documentation with the new version of rsyslog that tells them what the config parameters that are now not supported did, and how to change the config to continue to work.
David Lang
If the latter (what we had before), we'll need to restore some of the content previously removed, but it is doable.
@rgerhards Your thoughts?
- I think it is acceptable to direct people that use outdated config constructs to a web resource for full details
- however, we need to actually redirect them
- there is the idea to provide a cross-reference of new to old: https://github.com/rsyslog/rsyslog-doc/issues/456 -- this might be one spot for redirection
- going into full-depth of obsolete legacy style in the current doc IMHO is not useful; it would require a lot of work, especially as at least I have long forgotten all the dirty details
- I agree that we should mention the obsolete legacy statements. The current doc partially tries to address this via "embedded cross-references", see e.g. here (bottom of page): http://www.rsyslog.com/doc/master/configuration/modules/omfile.html IMHO this is actually useful
- I think we should remove obsolete legacy config examples, as examples just tend to be copied, and so by providing them we actually would spread their use
On Tue, 16 Jan 2018, Rainer Gerhards wrote:
- I think it is acceptable to direct people that use outdated config constructs to a web resource for full details
- however, we need to actually redirect them
what if they aren't reading with a browser, or don't have Internet access?
- there is the idea to provide a cross-reference of new to old: https://github.com/rsyslog/rsyslog-doc/issues/456 -- this might be one spot for redirection
- going into full-depth of obsolete legacy style in the current doc IMHO is not useful; it would require a lot of work, especially as at least I have long forgotten all the dirty details
- I agree that we should mention the obsolete legacy statements. The current doc partially tries to address this via "embedded cross-references", see e.g. here (bottom of page): http://www.rsyslog.com/doc/master/configuration/modules/omfile.html IMHO this is actually useful
I don't think we need to go in deep depth, but we should be able to say $someconfigoption was replaced by parameter X
- I think we should remove obsolete legacy config examples, as examples just tend to be copied, and so by providing them we actually would spread their use
I very much agree with this now.
what if they aren't reading with a browser, or don't have Internet access
you see my actually surprised - aren't most folks able to access it from the workstation the ssh in to the prod system (or config creation system, actually)? Note: this is not a rhetoric question but a real one ;-) Also, I personally know no admin who actually has installed the html doc on such critical systems. Quite honestly, not even installed somewhere at all...
I don't think we need to go in deep depth, but we should be able to say $someconfigoption was replaced by parameter X
That's what it does.
not meant offensive: I personally would really prefer if at this stage we put all that effort into actually improving that current doc than think about what to do with v5. It may sound harsh, but we are using valuable time (and lots of that) to discuss about something that IMHO could gradually improve the current state whereas we also could do drastic improvements. Just my 2cts and gut feeling...
On Tue, 16 Jan 2018, Rainer Gerhards wrote:
what if they aren't reading with a browser, or don't have Internet access
you see my actually surprised - aren't most folks able to access it from the workstation the ssh in to the prod system (or config creation system, actually)? Note: this is not a rhetoric question but a real one ;-) Also, I personally know no admin who actually has installed the html doc on such critical systems. Quite honestly, not even installed somewhere at all...
most folks are, but I've had cases where I'm in the datacenter working on something and don't have ready access out.
I'm understanding these changes to apply to all versions of the docs, not just html, internet hosted versions.
I don't think we need to go in deep depth, but we should be able to say $someconfigoption was replaced by parameter X
That's what it does.
not meant offensive: I personally would really prefer if at this stage we put all that effort into actually improving that current doc than think about what to do with v5. It may sound harsh, but we are using valuable time (and lots of that) to discuss about something that IMHO could gradually improve the current state whereas we also could do drastic improvements. Just my 2cts and gut feeling...
My only objection was seeing what looked like a proposal to remove all references to the obsolete parameters from the current docs with the 'but they are in the v5 docs' excuse.
If we are still leaving enough bread crumbs in the current docs so that someone faced with a legacy config that includes obsolete things in it can still look through the docs and figure out roughly what is happening, and how to implement the proper advanced replacement, then I'm happy.
If we are still leaving enough bread crumbs in the current docs so that someone faced with a legacy config that includes obsolete things in it can still look through the docs and figure out roughly what is happening, and how to implement the proper advanced replacement, then I'm happy.
(maintainer hat off): I think this sounds like a good compromise -- and also like something that is useful in practice as well. @deoren what do you say?
@davidelang: If we are still leaving enough bread crumbs in the current docs so that someone faced with a legacy config that includes obsolete things in it can still look through the docs and figure out roughly what is happening, and how to implement the proper advanced replacement, then I'm happy.
@rgerhards: (maintainer hat off): I think this sounds like a good compromise -- and also like something that is useful in practice as well. @deoren what do you say?
So to clarify, the plan is to:
-
Update module docs to include a short list (list only, not details) of
obsolete legacyformat directives to act as a finding aid for currently supported module parameters -
Skip bundling the old branch of documentation in the current doc tarballs
@davidelang: Last I looked (sorry for not paying attention here), I thought we agreed on the need for three sections
Advanced Legacy Obsolete Legacy
Recent work has purged the obsolete legacy format section from docs, but it sounds like I missed the goal of only pruning examples, and leaving behind other coverage of the
obsolete legacy format.
I don't know if there was a plan to make specific sections for the advanced and basic formats, but explicitly doing so could be useful.
For cases where it wouldn't apply, we would be explicitly spelling it out to make that clear. For cases where it does apply, we could highlight the differences. I think one good example of where having sections for all three formats could be useful would be the omfwd module (http://www.rsyslog.com/doc/master/configuration/modules/omfwd.html).
The "legacy"' example there (ignoring the $ModLoad directive) is think of as the basic format, so that would go under that section. The obsolete legacy format directives would be listed as a simple single-item list (without any explanation of what they're used for) and the advanced section would cover the other content.
I'd have to work with it some to get a good feel for organizing the content, but doing so would be useful in building a template for future modules and for standardizing the existing ones.
On Tue, 16 Jan 2018, Deoren Moor wrote:
- Update module docs to include a short list (list only, not details) of
obsolete legacyformat directives to act as a finding aid for currently supported module parameters
A little more than a list. We don't need full details, but if the names of the advanced parameters aren't obvious, it should be something like
$someoldparameter newparametername
there may be some odd cases (like the misnamed TCP parameters) where more explination is needed.
The key objective is to remove the examples that use the obsolete parameters because they are an 'attractive nuisanse' that lead people to using them more.
On Tue, 16 Jan 2018, Deoren Moor wrote:
- Update module docs to include a short list (list only, not details) of
obsolete legacyformat directives to act as a finding aid for currently supported module parametersA little more than a list. We don't need full details, but if the names of the advanced parameters aren't obvious, it should be something like
$someoldparameter newparametername
there may be some odd cases (like the misnamed TCP parameters) where more explination is needed.
Understood. I had in my head that the cross-reference (#456) would be a separate document, but I think I'm probably confusing that with the list of directives that are no longer supported in any way (e.g., $OptimizeForUniprocessor as discussed on #454).
The key objective is to remove the examples that use the obsolete parameters because they are an 'attractive nuisanse' that lead people to using them more.
Understood.
@davidelang @rgerhards What do you think about listing the obsolete legacy format equivalent in the tables used in this prototype format (example taken from the table in PR #476):
http://rsyslog.whyaskwhy.org/imuxsock_parameter_syntax/configuration/modules/imuxsock-parameter-headers.html
That might be a way to have the cross-reference right there with relevant current info for a parameter.
I'm not sure exactly what you are asking, but I have no problem with that format. k
@davidelang @rgerhards What do you think about listing the
obsolete legacyformat equivalent in the tables used in this prototype format (example taken from the table in PR #476):http://rsyslog.whyaskwhy.org/imuxsock_parameter_syntax/configuration/modules/imuxsock-parameter-headers.html
That might be a way to have the cross-reference right there with relevant current info for a parameter.
@davidelang: I'm not sure exactly what you are asking, but I have no problem with that format.
Wait until about 40 minutes after this hour (when the next scheduled build should on my VPS should complete), and then check out this page (attempting now will give a 404):
http://rsyslog.whyaskwhy.org/imuxsock_parameter_syntax/configuration/modules/imuxsock-parameter-headers-with-obsolete-legacy-info.html
Quick preview:
ah... except for one thing "equivalent" is not 100% correct. But I don't yet have a better term. But usually it is not really equivalent, just kind of. The obsolete legacy format semantics are often different due to the way that it can be specified out-of-context, multiple times etc. So it intends to do a very similar thing, albeit still (sometimes notable) different than in current format. I think I began to use the term "equivalent", but if we could come up with a somewhat better one, that would be great.
Nevertheless, I think the way this is done (in table right at the current format description) is a great way to do it. I am strongly in favor of that!
@rgerhards After posting that screenshot I came to roughly the same conclusion. I ended up going with the same language used in the formats description page: "obsolete legacy directive"
Live view:
http://rsyslog.whyaskwhy.org/imuxsock_parameter_syntax/configuration/modules/imuxsock-parameter-headers-with-obsolete-legacy-info.html
@rgerhards: Nevertheless, I think the way this is done (in table right at the current format description) is a great way to do it. I am strongly in favor of that!
Awesome, that sounds like the way to handle this then, at least in as far as the next steps for the work on PR #476. Regarding the topic of maintaining a branch for coverage of the obsolete legacy format, perhaps we can post-pone it for a bit until rsyslog/rsyslog#2383 is resolved.
sounds good.
On Wed, 17 Jan 2018, Deoren Moor wrote:
Date: Wed, 17 Jan 2018 23:24:01 -0800 From: Deoren Moor [email protected] Reply-To: rsyslog/rsyslog-doc <reply+0021b24ff07b45e2b7ba074fec7a4c136017d4bf5a816b4892cf0000000116780d9 [email protected]> To: rsyslog/rsyslog-doc [email protected] Cc: David Lang [email protected], Mention [email protected] Subject: Re: [rsyslog/rsyslog-doc] Consider opening up maintenance of the v5-stable branch (#499)
@rgerhards: Nevertheless, I think the way this is done (in table right at the current format description) is a great way to do it. I am strongly in favor of that!
Awesome, that sounds like the way to handle this then, at least in as far as the next steps for the work on PR #476. Regarding the topic of maintaining a branch for coverage of the
obsolete legacyformat, perhaps we can post-pone it for a bit until rsyslog/rsyslog#2383 is resolved.
sounds like we are in agreement! The new caption is also good. Great work! :-)
@rgerhards What version (or series) of rsyslog was the last to add obsolete legacy format directives? I'm working on the tables and am adding misc "TODO" entries to trigger build warnings until all tables have something in place for that column.
Some parameters are clearly marked as being introduced in v7.x or v8.x. The latter I assume is probably safe to consider "none" as the answer, but I figured it was best to ask just to make sure.
It should be safe to assume that v6 was the cutover (not perfectly accurate, but that was long enough go that it's not worth getting more precise) k
@davidelang: It should be safe to assume that v6 was the cutover (not perfectly accurate, but that was long enough go that it's not worth getting more precise)
Thanks, that's good enough for me. I'll place "none" in the field for any parameter that showed up after v6 then.