mhhh.. posted too fast. What I really want to say is: it is not really that much effort to maintain doc for various versions (at least if we focus on new-style, v5 & new-style is definiely quite a bit more effort, but still less thank I think is perceived). The core reason is that features are *added*, not removed. So you always *build up* on the previous doc. With proper branching and merge discipline, it really is almost effortless to work on the multiple versions.
The root problem today, as I see it, is that the core doc (oldest version) is not good. That needs to be changed - the rest then is again "without effort". Rainer On Mon, Dec 16, 2013 at 4:31 PM, Rainer Gerhards <[email protected]>wrote: > 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.
