On Mon, Dec 16, 2013 at 4:12 PM, Radu Gheorghe <[email protected]>wrote:
> My comments about ditching pre-v8 stuff and old config format are about > priorities. Old versions and formats should be documented eventually, but > the new format and new versions should have higher prio IMO. So at least > someone willing to try the latest version (who might become a contributor!) > can find the needed docs. > > Instead of taking one module at a time and documenting it for all the > versions + the old-style format, I would start by showing what it does in > 8.1.3. Some modules are not ported to v8 yet, so I'd skip them in the first > phase, because they have a higher chance of becoming obsolete. > > Only after v8 docs are done properly I'd start adding: > - old-style config stuff > - info about older versions > - modules that weren't ported to v8 yet > > Otherwise we'd have a higher risk of staying where we are: lots of info > scattered all around the Internet, because documentation won't be able to > catch up with features. > > Think about how you patch code. How do you do it? > 1. fix all the bugs of the latest version first, then move on to > backporting > 2. do a fix, backport to all the "significant" versions, then move on to > the next fix > > not in rsyslog ;) fix in affected oldest (somewhat supported) version, then upport - usually. I agree, though, that minor things (or very complicted, design-based issues), I fix in the latest version. The "fix in oldest" aproach IMHO has tons of advantages and results in less work. If you haven't seen: http://blog.gerhards.net/2013/12/how-i-maintain-multiple-rsyslog-versions.html Rainer > I think 1. is better for most situations, because the latest version is > where effort is worth investing. And I think it should be the same with > documentation. > > And I don't think the old format is good for anything else than backwards > compatibility. Which implies familiarity with sysklogd users, etc. Valid > arguments, but we shouldn't cling on to that. > > Take the omfile example. Using explicit omfile shows users that rsyslog is > modular and that it has other options beyond the prio filter and the path. > Makes you look it up if you need to. How do you search for docs if "*.* > /var/log/messages" doesn't work? You don't, you complain that rsyslog > sucks. I've seen people do that, and who can blame them? You'd expect > people to google "why *.* doesn't work"? > > If a new-style config format is worse than an old one in any significant > way, it's probably a bug. Either of code or of documentation. Currently, I > think most such stuff is related to documentation. > > 2013/12/16 Rainer Gerhards <[email protected]> > > > On Sun, Dec 15, 2013 at 3:25 PM, Rainer Gerhards > > <[email protected]>wrote: > > > > > Branches also make maintaining multiple versions really easy. I'll > blog > > > tomorrow how i do it for rsyslog. > > > > > > > As promised, this is a description of my workflow: > > > > > > > http://blog.gerhards.net/2013/12/how-i-maintain-multiple-rsyslog-versions.html > > > > It's *extremely* easy to mange the multiple versions. > > > > In spite of this, my recommendation to the doc project is > > > > a) create v5-stable, v7-stable, v7-devel, (master) branches > > b) import rsyslog v5-stable doc to v5-stable > > c) merge v5-stable to v7-stable (git pull . v5-stable) > > d) import rsyslog v7-stble doc to v7-stable; you now get a diff, commit > > that one > > e) merge v7-stabe to v7-devel > > f) import rsyslog v7-devel doc to v7-devel; you now get a diff, commit > that > > one > > g) now it beomces a bit tricky, checkout master, delete evertyhign, > commit > > (sorry....) > > h) merge v7-devel into master > > i) import rsyslog master doc to master; you now get a diff, commit that > one > > > > At that point, you have the same structure that the main project has and > > you can now easily make doc updates using the described workflow. It's > > really worth it! > > > > I'd suggest to support v5-stable, even though it is outdated. Many > distros > > ship it (even older versions...), so enhancements to it would definitely > > help improve rsyslog perception. > > > > Sorry again for not thinking enough in depth about it initially. As I > said, > > I hand't expected we get such good results so quickly ;) > > > > @James, please let me know how you think you'll proceed, as this affects > > the way I contribute updates to the doc. > > > > Rainer > > _______________________________________________ > > rsyslog mailing list > > http://lists.adiscon.net/mailman/listinfo/rsyslog > > http://www.rsyslog.com/professional-services/ > > What's up with rsyslog? Follow https://twitter.com/rgerhards > > NOTE WELL: This is a PUBLIC mailing list, posts are ARCHIVED by a myriad > > of sites beyond our control. PLEASE UNSUBSCRIBE and DO NOT POST if you > > DON'T LIKE THAT. > > > _______________________________________________ > rsyslog mailing list > http://lists.adiscon.net/mailman/listinfo/rsyslog > http://www.rsyslog.com/professional-services/ > What's up with rsyslog? Follow https://twitter.com/rgerhards > NOTE WELL: This is a PUBLIC mailing list, posts are ARCHIVED by a myriad > of sites beyond our control. PLEASE UNSUBSCRIBE and DO NOT POST if you > DON'T LIKE THAT. > _______________________________________________ rsyslog mailing list http://lists.adiscon.net/mailman/listinfo/rsyslog http://www.rsyslog.com/professional-services/ What's up with rsyslog? Follow https://twitter.com/rgerhards NOTE WELL: This is a PUBLIC mailing list, posts are ARCHIVED by a myriad of sites beyond our control. PLEASE UNSUBSCRIBE and DO NOT POST if you DON'T LIKE THAT.
