I think the current status of the Trellis docs – and the presence or lack of validations generally – reflects the fact that so far Trellis is exclusively the product of volunteer work. Volunteers have donated hundreds, maybe thousands, of person hours to offer a tool that is free to use. That said, I wish it were more polished and complete.
Regarding the status of Trellis and its docs, I think its current status is a tool that offers great ideas and spares people a lot of labor. However, it doesn’t yet spare people having to understand some Ansible basics (like Ansible host groups) or just other dev tool basics. Some have posted threads indignant that the docs didn’t dedicate prime docs real estate at the beginning to offer OS-specific instruction on basic concepts that in my opinion should already be familiar to devs who have even minimal involvement with servers. (Edit: I removed unnecessary example topic.) It’s ok for anyone to not know those concepts. I didn’t know them before getting involved with Trellis. But at this point Trellis doesn’t try to provide documentation for all the basics of setting up a development environment.
It would be great if we were to create or link to materials for all such knowledge prerequisites, but it would take a lot of time to create an effective uncluttered presentation that serves novice and expert alike. At present, volunteers are just short on the time required to coordinate such an effort. I’d love to try it, but I’ve had to discipline myself to focus on more global structural issues and improvements that could have more far-reaching benefits, and which could necessitate a different set of docs instructions anyway. So, I personally have been taking the attitude of “I’ve gotta do the restructuring first, then I’ll know what docs to create.”
The issue you encountered of conflict between staging vs. production vars is a bigger issue than others, however, and shouldn’t be put off. I’m sad you encountered it. Nonetheless, to illustrate the volunteer situation, note that I proposed a validation for this specific issue 1.5 years ago but no volunteers have reviewed it (see one_env_group_only stuff in roots/trellis#562). Nor have any volunteers added anything to the docs on the issue (docs are open for PRs). I don’t fault anyone, and to be fair, I let that #562 validations PR go stale because it’s an example of something I expect will be revamped anyway in those “structural changes” I mentioned I’m exploring.
I don’t say any of this with bitterness, nor with criticism of anyone (e.g., volunteers). Every contribution from volunteers to the project and this forum is a gift. I don’t say any of this as an excuse. I’m only giving my best account of the situation. I agree the docs need help and some examples grow embarrassingly out-of-date. I think that’s just the status of our all-volunteer situation.
Right now the docs are fairly bare, suitable for simple examples and setup, but when issues or needed customizations arise, people will have to familiarize themselves with Ansible and the Trellis implementation. Trellis is pretty ideal for someone with knowledge of server issues, for someone who mostly already knows what needs to happen (server setup/configs) but just needs to learn how Ansible/Trellis automates it.
Figuring out what Trellis is doing is usually pretty straightforward given that the roles and tasks are just YAML, each with a straightforward name parameter like Create WordPress configuration for Nginx. In that example you can see how the Nginx conf file is created and its dest which uses the item.key from the Ansible-basic with_dict loop. At present, a user wishing to resolve some issues or make customizations to Trellis will need to examine the “code”, not just the docs. I think people don’t try doing so often enough. I think they don’t realize that Trellis tasks are easily examined; just a list of tasks that Trellis steps through in linear fashion.
You indicate that so far you’ve invested two days getting familiar with the tools (I realize its probably more). As it seems you will seek more than just the most basic use, I expect you will end up investing at least a few more days initially, then again on various occasions in the future. Given that expectation, you may decide that’s not an investment you want to make. Honestly, to me, it would be worthwhile to invest two weeks – or even two months – to get a handle on tools that could be a powerful and central part of your dev toolset.
Again, my impression is that you’re already proficient with the dev/server issues involved and thus are likely to profit more than most from investing in making Ansible part of your toolbox. You already know that learning tools takes time. But time is limited and I see it as perfectly respectable to prefer paid services to handle these particular matters so that you can “be done with it and focus on [your] WP dev work.”
Best wishes, and thanks for the candid feedback. This can serve as a reference for improvements. It’s valuable perspective that easily fades in memory of those who have been familiar with the tools and their quirks for some time.