Saw that blog post, thanks! And I think once you have a solid base, the "merge upward" thing is awesome.
Though I think now we're trying to do a complicated, design-based thing with the docs, no? 2013/12/16 Rainer Gerhards <[email protected]> > 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. > _______________________________________________ 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.
