I should point out that even in v5, the core *concepts* are the same, and so is a lot of useful doc. "Just" the config language has improved, but if you think about howto's etc what you need to describe is eaxtly the same -- if just comes with two different sets of config statements. So you could probably for howto types of thing do a commn document that ends with a sample config for v5 and v7.
Of course, that doesn't work out for howtos which rely on new features... Rainer On Mon, Dec 16, 2013 at 4:41 PM, Boylan, James <[email protected]>wrote: > Actually I'll be implementing a similar solution to what Rainer has for > code in the documentation. I'll be building out the structure in the > v5-stable documentation, then merge that document set into v7-stable. In > v7-stable I will add the items that have changed and any new features then > merge into v7-devel. Then continuing up the path until I hit master. This > way we are able to make changes to the version where the change starts and > then merge them up just like it is done with the main code. > > -- James > > -----Original Message----- > From: [email protected] [mailto: > [email protected]] On Behalf Of Radu Gheorghe > Sent: Monday, December 16, 2013 9:38 AM > To: rsyslog-users > Subject: Re: [rsyslog] [doc] versioning > > 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-versi > > ons.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-versi > > ons.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. > _______________________________________________ > 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.
