Update website for SFML 2.3.2

[eXpl0it3r]

Once SFML has been tagged as 2.3.2, this PR needs to be updated with:

• New documentation
• New binary sizes

In the meantime feel free to check that everything is there.

[Bromeon]

Why new documentation? By definition of a patch release, the API does not change.

I understand that documentation can also be fixed in the course of a patch release, but these mistakes are mostly minor. We can either leave 2.3 until 2.4 comes out, people needing up-to-date documentation will build it from source anyway, and it would make our patch releases easier. Alternatively, we can override 2.3 with 2.3.1 as soon as its available. I don't see a reason to provide both 2.3 and 2.3.1 -- it makes no sense to look at the same API documentation but with more mistakes.

As such, I suggest we keep only the link www.sfml-dev.org/documentation/2.3/ alive, remove/redirect www.sfml-dev.org/documentation/2.3.1/ and don't even start with www.sfml-dev.org/documentation/2.3.2/.

[eXpl0it3r]

I also don't see a reason NOT to provide both.

[Bromeon]

Well, we should have a reason for the things we're doing, not the ones we're not doing 😉

What's the point of providing both? As I mentioned, it makes no sense to look at the same API documentation but with more mistakes. A previous patch version of the same minor version is nothing else: documentation of the identical API, but potentially more mistakes.

Furthermore, we could simplify the URLs and need fewer pages. It's consistent with tutorial URLs. We don't have pages that are never linked to, like at the moment. Links to older patch versions automatically benefit from documentation improvements.

[eXpl0it3r]

Well, we should have a reason for the things we're doing, not the ones we're not doing

If you want to argue that way, then the reason is simple: Every version gets a new update. Which directly leads into the question: Why not patch versions?

Documentation gets fixes and telling people to go build their own because we don't want to have more pages on the websites to get a properly fixed version is in my opinion not the way to go.

Lets just hear everyone's opinion and do what the majority wants. I personally see no point in "discussing" stuff that's purely opinion based. 😉

[Bromeon]

Which directly leads into the question: Why not patch versions?

See my last two posts 😀

Documentation gets fixes and telling people to go build their own because we don't want to have more pages on the websites to get a properly fixed version is in my opinion not the way to go.

You may have misunderstood me. I'm perfectly fine with providing only docs for the latest, most correct patch version. However I don't see why we would mislead people by documenting the identical API with different levels of correctness.

Lets just hear everyone's opinion and do what the majority wants. I personally see no point in "discussing" stuff that's purely opinion based. 😉

I brought a ton of actual arguments, let's hope others don't see it as purely opinion based 😉

[LaurentGomila]

I think it's obvious that we don't need the documentation for 2.3.0 and 2.3.1 when we have 2.3.2. The website should just contain /documentation/2.3, generated with the latest patch version of that branch. It's not an opinion, just common sense ;)

[eXpl0it3r]

"ok"

[TankOs]

Please don't forget that a lot of professional users and companies can't switch versions as quickly as hobby developers. That means that once they stick to a version, they will do so for a longer time, to prevent upgrade issues. And that also means that they want the documentation for that particular version.

While a patch release is not allowed to change the API, it is still allowed to change things in such a way that the docs get ouf of sync. The least result would be confusion, the worst an error.

Since I always like to be consistent in every way, I also suggest to generate documentation for each version and not make exceptions just because changes might be small. We have enough HDD on the server, so that's clearly no issue.

/documentation/2.3 should of course go to the latest docs, but a redirect in this case.

So I guess it's 2:2 now, we need more opinions. :P

[Bromeon]

While a patch release is not allowed to change the API, it is still allowed to change things in such a way that the docs get ouf of sync. The least result would be confusion, the worst an error.

How is that possible? The only thing that's allowed during a patch release are bugfixes, also in the documentation -- no change in behavior. Why should we leave people with docs containing errors when an improved version that targets the same API exists?

The confusion and error you're talking about is much more likely to develop when people stick to outdated and erroneous documentations because we still provide them.

Talking about consistency is also ironic, because providing patch versions is something we don't do for tutorials, either. 😉

---

Please don't stick to something just because it seems "natural", when there are so many reasons against it, and it doesn't make sense from an objective standpoint. Most other libraries provide even only the latest minor version on their website. Please read my first two posts again and try to understand everything -- I've really put some effort in making it convincing, and it's sad if the arguments are just ignored and countered by "I don't see a reason NOT to provide both", "we have enough disk space" and similar 😞

[LaurentGomila]

Let's state it differently: if the doc for 2.3.2 leads to confusion or mistakes when used with 2.3.1, then we clearly did something wrong in 2.3.2.

The purpose of patch versions is to be a drop-in replacement for their entire minor version branch. In other words, you can use any 2.3.x, you'll get the same API, same behaviour. Just less bugs as the patch number increases.

Professionals and companies are the exact ones for who we added patch releases. So that they can upgrade their SFML libraries with no consequence other than getting fixes on critical bugs. If we start to differentiate patch versions by API / behaviour or whatever you have in mind, then we break this contract.

[TankOs]

How is that possible? The only thing that's allowed during a patch release are bugfixes, also in the documentation -- no change in behavior.

Is that true? A fix can definitely change behavior -- exactly then, when behavior was faulty. Patch releases are required to not break the API and ABI, that's it.

Why should we leave people with docs containing errors when an improved version that targets the same API exists?

Because if those people use outdated versions (for good reasons, like I stated above), they have to use documentation that complies with that version. I don't want to think about all possible cases, I just want to make sure that there practically can never be issues with out-of-sync docs. "Better safe than sorry".

The confusion and error you're talking about is much more likely to develop when people stick to outdated and erroneous documentations because we still provide them.

We could add a banner to the documentation pages, in red, that tell the user he's reading outdated material.

Talking about consistency is also ironic, because providing patch versions is something we don't do for tutorials, either. 😉

Good that you mention it, because yes, I would even copy over the tutorials. They will never change in patch releases, most likely, but really: What's wrong with providing a full set of to-be-guaranteed compatible resources for a release? This happens at no cost.

Please don't stick to something just because it seems "natural", when there are so many reasons against it, and it doesn't make sense from an objective standpoint.

I stick to something when I think it's correct, this is called an opinion. I will not discuss my way of discussing with you. In a discussion, calling the own standpoint objective doesn't help at all -- it's purely subjective, in my opinion (as we can see, because I do see it differently).

Most other libraries provide even only the latest minor version on their website

Just because others do it doesn't mean we have to do it, as well.

Please read my first two posts again and try to understand everything -- I've really put some effort in making it convincing, and it's sad if the arguments are just ignored and countered by "I don't see a reason NOT to provide both", "we have enough disk space" and similar 😞

I did understand everything. I just don't want to quote and reply to every single word you write. I rather find it sad that I'm being called an ignorant. :) I just brought my arguments to the table, and I don't think that I'm required to reply to anything that has been written prior to that.

[TankOs]

I would like to quote eXpl0it3r, again:

Lets just hear everyone's opinion and do what the majority wants. I personally see no point in "discussing" stuff that's purely opinion based. 😉

I've said everything I wanted, let's wait for the other team member's opinions. @binary1248 @mantognini @MarioLiebisch @sonkun (Grimshaw is not even listed as a member?!)

[mantognini]

I know it won't help much but: I've no strong opinion about the two options here. So I'll raise my white flag here. =P

[Bromeon]

Good that you mention it, because yes, I would even copy over the tutorials. They will never change in patch releases, most likely, but really: What's wrong with providing a full set of to-be-guaranteed compatible resources for a release? This happens at no cost.

That's not true for tutorials. When we fix something, we apply it also to past versions (because we can, as opposed to docs which is generated from code). So the maintenance effort is increased when we have multiple, highly redundant pages.

I stick to something when I think it's correct, this is called an opinion.

I'm okay with your opinion, but the discussion is meaningless if everybody just states his own opinion without reacting to other's arguments.

I rather find it sad that I'm being called an ignorant. :)

I did not do that, please read more carefully 😉

Just because others do it doesn't mean we have to do it, as well.

No, but if everybody does it, we should at least understand why.

I know it won't help much but: I've no strong opinion about the two options here. So I'll raise my white flag here. =P

Well, then read the discussion again, and form an opinion 😛
Otherwise this will be another endless thing...

[TankOs]

I'm okay with your opinion, but the discussion is meaningless if everybody just states his own opinion without reacting to other's arguments.

In the end, it's all about finding all possible solutions and choosing one. It's not about defeating other people's opinions. Even if you and Laurent talk about "common sense" and that your suggestion is "objectively" right, others might not comply with that. Btw, such statements rather disqualify from discussions (with me) instead of bringing them forward, because it's like saying "You are wrong, we are right, because it's how it is.".

Like said, I have nothing more to add to the actual "problem", so I'm looking forward to more opinions, and I'm fine with whatever solution will come out of it.

[Bromeon]

Even though I did not actually say my standpoint was objective, I agree that the wording was unfortunate. Sorry for that. I was just a bit annoyed that I took quite some time to list so many arguments, and nobody responds to them, and eXpl0it3r even answers with null-sentences like "I also don't see a reason NOT to provide both" despite the obvious presence of reasons just one post above.

I hope we find a good solution to this, we definitely have more important tasks at hand 😉

[Bromeon]

So... more opinions? Does everybody hold his point of view?

[binary1248]

The API is only the programming interface, that doesn't change in a patch in order for code to stay compatible. However, there would be no purpose to a patch if neither the interface nor the behaviour of the library actually changed would there? And since we document behaviour as well, patches imply documentation change.

[Bromeon]

However, there would be no purpose to a patch if neither the interface nor the behaviour of the library actually changed would there?

Patches fix bugs, and bugs occur where implementation and documentation differ. Usually the former is wrong, not the latter.

Maybe we should look at concrete examples 2.3.2 vs 2.3.1 vs 2.3... Has there been any change in documentation between those releases? And not just one that could as well have been included in the master branch, but one that actually reflects behavior changes in the underlying patches?

More opinions (rest of the team and community)? We should finally bring this to an end...

[TankOs]

Has there been any change in documentation between those releases?

Unfortunately I don't have the time to search for one, but I can easily think of an example that might happen, in a similar way:

/** Do something.
 * @param value The value to use. Prints an error message if invalid.

"Prints an error message if invalid." can be added in a patch, as well as the std::cout part in the implementation, of course.