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.
