On Sun, 15 Dec 2013, Radu Gheorghe wrote:
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).
distros are going to ship 7.x, so it will be around a LONG time, especially if
it's in RHEL. This is why we still get a lot of questions about 5.x, so we
probably need to go back to it as well
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.
sometimes it's much easier to do the old-style config, and there are a lot of
docs out there with the old style (not to mention configs), we need people to be
able to understand what these existing docs and configs are talking about. As
well as how to convert from one style to the other.
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.
for this I'll let the doc maintainers experiment for a bit, they are the ones
who will suffer the most with massive numvers of versions to manage. If they
create the tools to do something like "fix this for all versions" or "fix this
for all 7.x versions" then it can work. If it gets to be too much work, they can
collapse the versions.
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.
for new features, you are correct that things _should_ just be added to the
latest -devel releases, but there are a lot of corrections, clarifications, etc
that people will come up with for older versions that will need to be applied
back to those docs.
David Lang
_______________________________________________
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.
