Hi Lukas, On Wed, Jun 19, 2019 at 01:44:26AM +0200, Lukas Tribus wrote: > Hello Willy, hello Tim, > > > On Sat, 15 Jun 2019 at 18:57, Willy Tarreau <[email protected]> wrote: > > > - ssl.cfg : 4 years with the most recent commit adding a > > > 'verify none' which is questionable. > > > > deleted, I agree with not spreading bad options by default. > > I disagree that the amount of the commits and its age are *the* metric > to measure the value of an example configuration. It's a fact that we > seldom make breaking changes to our config parser, that's a good thing > and it's why we don't need to update the example sections for every > stable release. We need to measure the merits of an example file based > on it's content. A short example configuration does not need frequent > updates and it's more useful, the *shorter* it is (as it focuses on > one aspect, allowing the user to quickly grasp the config-concept).
I generally agree with this. The problem I've had is that as usual, time for unimportant cleanups was only found at the end and that I stumbled upon these files again that I seldom find using git grep when looking for something and which have become mostly irrelevant or even misguiding users. So I preferred to get rid of them from this directory before these ones got packaged again and used as a starting point for many years, even if we reintroduce replacement files later. But I'm in favor of creating new files if needed, maybe better organized if needed, or even reintroducing a few of them after a lift up or as-is. We don't break any stable release by adding doc, we can by removing some in the stable cycle. I'd have gone even further to be honest if I could have sent earlier notification, and for example I think that the whole "tests" directory should be deleted now. > Of course we need to discuss the removal of obsolete ones, which > brings me to the second point: > > Could we allow some more time for such things to be discussed? A few > working days instead of less than 2 hours? I get it, you wanted it > done in 2.0, but that's not what I'd call asking for objections. Agreed, that's a direct result of my point above. I was checking the places where the linux2628 target was mentioned, ended up on the old spec file (which one person privately asked me to reintroduce since it does work out of the box for them, so at least it's a confirmation it's still OK even after so many years without any maintenance). I think this time we could try to perform more aggressive cleanup early in the cycle for 2.1 so that it's less of a last-minute surprise (for example the tests directory might still contain some junk). > In the specific ssl example, yes, the "verify none" directive does not > belong there, instead, it should have been a ca-file directive. Other > than that, I don't see neither why this example would be outdated, We can remove the global maxconn directive as well. > nor > where we could point people asking the extremely specific "howto ssl?" > question instead. Indeed. > > As history has shown the examples tend to be neglected. > > History has also shown that documentation is neglected. But we can > point people to specific examples, just as we can point people to > documentations. > > That's why we need examples. To point people to them when they ask. That's precisely why examples were added in the first place, though I remember having left some very old ones there for a while dating from before the frontend/backend split, doing horrors using cookies and chaining multiple layers this way, that I definitely didn't want anyone to discover anymore. > > if you start from the need to implement something, you search > > it in the architecture manual and you copy-paste a look-alike > > config that you can then extend. > > I was unaware that that's your intention with the architecture manual, > I always saw it as an explanation of basic load-balancing concepts > applied to haproxy (principal features like load-balancing and health > checking), but I realize now what you mean. The original goal of the architecture manual was to achieve something I've found in other product's architecture manuals that I had found extremely useful in the past : you've just unpacked and plugged your new product, you're in front of it with zero config, you open the manual and think "let's find an example looking more or like the architecture I'm trying to deploy", then you copy-paste a more or less matching example config, possibly have to deploy some config on external components as well, and from this you can continue to adjust your config. > However for a 1400 lines document with 4 commits in the last 10 years, > all 4 of which typo/spelling fixes only, we cannot exactly claim > success. That's why I wanted to kill it a long time ago and to replace it with the wiki. There's normally a note at the top of the architecture manual saying something like "this is obsolete, don't use it". > If we want to retire the examples/ directory and put everything in one > file, we probably need to revamp the architecture manual completely > and create something that Cyril can use for the HTML converter. I just want to totally kill this manual. *Everything* in it is obsolete. But when I suggested to kill it a few years ago someone told me "if you kill it before replacing it, nobody will be able to use it as an inspiration to create the new one". That's fair in my opinion, though over the years it didn't work well either. > Otherwise and in its current condition, people are probably not gonna > find it, and we'd also have a hard time referencing single examples in > there. > > I'm really not sure if this is all worth it and quite frankly, don't > get the problem with single example files in the examples/ directory. > Explanations can be inline with the configuration, so it's even > lighter to read than an example in the architecture manual. Sure. > I'm not sure about the gh-wiki, I don't know how it works technically I think that the usage doc (typically the arch manual) should not be specific to one version, otherwise it slowly dies like the arch manual that was written for 1.1.something. The wiki may continue to be updated (once it does contain enough value for people to be interested in improving/fixing it). > and I'm a bit afraid that we don't have the actual content in *our* > git repositories. Also unsure about if we really still own the content > once we put it up there. These are fair concerns. My understanding was that these are stored in a different git repo that we can download. It's just the wiki which creates the commits each time you update. Ah indeed, the repo is "haproxy.wiki.git" there. > This is different than feature requests or > issues, because those are processes that start and end, while > architecture guides and everything referenced in the "Proposed plan" > is mostly here to stay and they are also *a lot* of work. When I > scrolled through the "proposed plan" I felt like this could be the > content for 2 or 3 books. Agreed, and it's clearly obvious everyone is terrified by the idea of doing anything there, just like it was a pain for me to write a plan. > Of course, simple example configurations are > not that valuable, but still, I'm unsure about that wiki. In fact if you look at the existing (dead) architecture manual, you'll find lots of ASCII art architecture examples. We can't ask people nowadays to provide network diagrams in ASCII art. And such diagrams are really important for such a manual. That's why I do think that a wiki is a good trade-off for this. I do also like the format of what is displayed on projects using "readthedocs" (which looks quite a bit like Cyril's doc by the way). I just don't know how to do something like this. Do you think we should reintroduce some simple updated example files in the examples directory based on usage ? For example we could have : - ssl-offload - ssl-to-server - ipv6-to-ipv4 - h2-to-http1 - server protection (maxconn, timeouts, etc) - sidecar ? Also we should indicate in such files which minimal version is expected for these to work, and at what date they were significantly updated. I prefer that users ignore an outdated file than to use it then figure it's too complicated for their simple use case while easier options are available (still thinking about the old 3-layer cookie-based config at an era where we have use_backend and use-server...). If such contents may be produced, wouldn't they be copy-pasted into the wiki with a bit of explanation ? If not, why ? Maybe the proposed plan is too scary to get anyone started ? I wanted to move it on a side so that people don't feel forced to follow it too much that that we can start to re-arrange contents later. I'm still totally open to suggestions. While I actually *like* to write doc, I don't have enough time to assign to this task anymore these days, and I'm torn between starting some doc myself and becoming a huge bottleneck for the rest of the project, or ensuring most people with knowledge of use cases can participate to this doc. The thing is that in this last case it must be sufficiently organized so that we do not create too much deviation between various people's practices. Cheers, Willy
