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... _______________________________________________ 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.
