2013/12/15 Radu Gheorghe <[email protected]> > 2013/12/15 Pavel Levshin <[email protected]> > >> >> 15.12.2013 15:51, Boylan, James: >> >> I agree. There is a strong need to identify versions in the >>> documentation. They question is where to draw the line. David has pointed >>> out that in the past its just been a matter of noting that certain >>> functions are available 7.5.8+, etc. Do we want to keep working from that >>> position? ie Break the documentation out to v7(-stable/-devel) >>> v8(-stable/-devel) and then do the same 'available in 7.5.8+' syntax? Or do >>> we want to hard lock the documentation versions to a specific release >>> version. >>> >>> The latter is more precise from a documentation perspective and less >>> work, but the former offers less confusion on what you can and can not do >>> with a specific version. I can see benefits to both methods, so feedback >>> on that would definitely be helpful. >>> >> >> As I've said before, latter is best for most documents. What does >> "7.5.8+" mean? Is is supported in 7.4.133? Is it present in 8.1.0? The >> answers are always not so trivial. Moreover, it is too easy to forget to >> write such a tag everywhere. Not every feature has this tag now, right? >> >> By the way, each document (when it is read by an user) should note which >> version it describes. It should be a part of template. >> > > +1. I think that's important, to keep users aware about where they are. > > Here's a crazy idea about versioning and how to make it easy. > > So the problem is that: > a) there's too little manpower (for now) to take care of the docs > b) there's too many docs to do > > Nothing much to do about a) for now - that's why we're trying to make the > docs better in the first place. So let's take a closer look at what b) is > about: > 1. Lots of features > 2. Lots of versions (5.x, 6.x, etc) > 3. devel- and stable- version types which make X+ version style hard to > follow > 4. old- and new-style configuration > > Nothing to do about 1., but here's what I suggest for the rest: > i) *only document master (8.1.3) and continue from there*. I wouldn't > even try to work with 7.x and older. It's too much work, and by the time > we're done, 7.x would be obsolete. For example, modules that won't be > ported to the v8 interface will probably fade away, and they can live on > the documentation that is spanned on the Internet now (which is how most > people get their rsyslog knowledge right now, IMO). > > ii) *don't even bother with the old-style config*. Double the effort, > triple the confusion. Even right now, everything supported (7.x and later) > works with new-style config. We tell everyone to upgrade, so it makes sense > to concentrate on the new stuff that we consider better. > > iii) *reconsider the versioning scheme*. That's the "crazy" part of the > idea. And it's something we can do quite easily with v8 because there's no > stable out yet. > > Here's how it could go: 8.1.3-devel is the latest. Further work is done on > master. Next devel would be 8.1.4, and master will continue to grow. Now > let's say that we want to base a stable on 8.1.4. We'd work put bugfixes on > the 8.1.4 branch and on master, and new stuff on master. When it all > matures, we'd have an 8.1.5 stable. And then we can continue with > 8.1.6-devel from master and so on. > > The only limitation I see is that once we decide to make 8.1.4 stable, we > couln't have a 8.1.5 devel until that stable is out. Unless cancel the > initial decision and we decide to make the next 8.1.5-devel into > 8.1.6-stable. Otherwise, 8.1.6-stable would miss some features of 8.1.5 => > confusion. > > I think this limitation wouldn't be such a big deal considering the > following: > - *a devel version (IMO) should be a preview of what the master will > become*, like a beta (now that beta doesn't exist). Another role might be > to make it easy for someone to experiment with the latest features. Though > if you want to be on the bleeding edge, you might as well compile from > sources (which is where documentation can come to the rescue!) > - if you really need to come up with a new devel it means: > - either you want to introduce new features on the next stable, in which > case you can always base the next stable on this new devel => no problem > - or you want to go MUCH further with development than testing and > documentation can follow. To me this is a problem because it creates too > much debt (which is something rsyslog seems to suffer for some time, > especially on the docs side). And this is something that needs to be > discussed&addressed, rather than worked around with different version > schemes. Example: I can bet that most users of rsyslog are not even aware > that it has queues and it's multithreaded. > > All this is just my opinion, so for those of you responsible (Rainer, > James), feel free to take only what makes sense, or discuss further or > ignore if I'm completely off, or... >
Just saw the Emails about branches, so I'd like to add: all I said about versioning would (in my mind) apply on both the code and the documentation. So any user can match the docs with the version one has. It would be nice to have a website that could follow those branches. Like the Logstash website does so nicely: http://logstash.net/docs/1.2.2/filters/grok _______________________________________________ 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.
