spockframework
Add migration guide Spock 1.x → 2.x to manual or separate document
Somewhere in another issue here (I don't remember where) we lately also talked about how I had difficulties migrating from Spock 1.x to Spock 2.x regarding my Maven setup. @Vampire held the opinion that this is all easily done and well explained somewhere in sample projects, but I had problems anyway and I am not the only one, see for instance this question which I have answered today because I learned by doing it already and had Björn to help me when I got stuck at some point, trying to get PowerMock running again.
The Spock manual currently just points to the JUnit manual for users to learn how to configure JUnit 5: http://spockframework.org/spock/docs/2.0-M2/all_in_one.html#_new_junit_platform
But JUnit 5 is not Spock 2.x yet. Furthermore, many users are not just migrating from Spock 1.x to 2.x but also have existing JUnit 4 or 5 tests. So how do I set up my Maven project in order to be able to run either Junit 4 + Spock or JUnit 5 + Spock tests? These are real world problems, and an explanation in the manual could ease the pain of many users, I suppose.
You are twisting my words a bit here.
All I said was, that the users guide also links to the example project which shows how to run Spock 2.x tests with Maven where it can be copied from, as it was solely about the Maven setup.
Your main problem was, that you could not use that template because you didn't want to use the gmavenplus plugin but something else.
In the tests itself there should not be changes necessary, at least none that are not listed in the release notes and the migration guide chapter in the users guide.
When it comes to other things like vintage engine or migrating JUnit 4 tests to Jupiter, then imho this is out of scope of the Spock users guide.
@Vampire, please do not take this personal. This ticket is about the Spock manual, not about what you said. As I mentioned above, you helped me so much in things I would not have needed help with if there was a Spock document not just describing how to use Spock but also Spock's architecture, and I am tremendously grateful for your support. But that kind of support does not scale well, so I consider myself lucky to have got it. :-)
I am talking about things like: Which module does what and depends on what? I mean both internal and dependency modules. How do they interact? Spock users are all developers, and that kind of documentation usually helps a developer understand why and how to configure something in a certain way beyond just copying a template or being pointed to another tool's documentation.
A certain amount of redundancy is helpful for "one-stop shopping" when it comes to getting something up and running. For instance - technically completely unrelated to Spock and only an example to get my point across - the Spring manual does not just point to the AspectJ homepage and say: "If you want to understand aspects, pointcuts, advices and all the aspect syntax, just read the AspectJ manual." No, the Spring manual covers the important parts relevant to Spring AOP (which feature-wise is just a subset of AspectJ), explains how to set everything up. Later same manual even explains the difference between Spring AOP and AspectJ and how to use the latter in the context of Spring. Is this somewhat redundant, considering the fact that AspectJ also has technical documentation? Oh yeah! But beginners do not have to figure out which parts of an external documentation source are relevant for them by themselves right from day one and have a way to get something up and running. The manual does not just explain how to use something but also provides a rough architectural overview necessary for understanding how it works, where there are limitations etc. This information is not exhaustive and power users can still consult external information sources, but you can read and understand it.
So as much as I appreciate the idea of keeping documentation concise, it seems my sweet spot is a wee bit closer to verbose than other people's. I am saying this because I sometimes answer questions on StackOverflow. I can answer them because I know already. But many things I do not know from the manual because the information is not there or something deserving more detail is just mentioned in passing in a sentence or two (sometimes even just half a sentence). I have sympathy for users and am just trying to view Spock from their point of view, imagining I have not worked with Spock for a few years but maybe just for a few hours or days.
Don't worry, I don't take it personally. I just don't like being quoted wrongly. Especially if that would mean I said non-sense. I did never said it is "well explained", or actually explained at all. I just said there is an example that one can use as blueprint. ;-)
Regarding the manual, I do not fully disagree that there could be more information, there is always room for improvement, but it also is not really up to me to decide. Here I just contributed my opinion, that things like Vintage engine or migrating JUnit 4 tests to Jupiter tests is out of scope for the Spock manual, as neither is necessary for Spock or is cooperating with spock. They are just neighbors as JUnit 5 platform engines on the JUnit 5 platform but are otherwise totally unrelated.
Btw. I remember you having said you would like to contribute to Spock, but are not deep enough into development / Spock code to do so. While you helping other users on StackOverflow, reporting issues, testing issue fixes and so on are imho also already great and important contributions, you could also open PRs with documentation changes that explain things better that you think are not explained well enough. For potentially questionable things you might ask first whether it would get accepted before doing the writing work. :-)