This is fantastic news, @Daphne Welcome!
Iāve been waiting for an initiative like this for a long time, so I just want to add a few words.
I maintain two apps, TimeManager and Link Editor. The biggest issue for me is lacking documentation on almost everything.
My tooling / setup and struggles it addresses
This is what has made life easier for me after a lot of trial & error, in no particular order:
- Releases ā I wrote a webhook server to publish releases to the appstore that I host on Uberspace to automate the process of publishing releases through a Github webhook. It has the added benefit that my apps are an exact copy of what can be found in my repositories, since no manual steps are involved in the publish process. Before I had this script, it took me a lot of time to publish releases properly, without missing any steps. I think it should be a no-brainer to add publishing tools to the Nextcloud developer ecosystem. Publishing manually is a recipe for disaster, especially for less experienced developers.
- Development environment ā I use the official nextcloud docker container for development after years of barely getting by with MAMP. How to set up a proper development environment on Windows, Mac and Linux should be in the developer documentation, too. Especially since it needs some hand-holding to get up-and-running properly. Iād be more than happy if the documentation and docker-compose file that I use for my apps could be re-used in Nextcloudās docs.
- End-to-end tests ā The docker-compose setup I also use to run cypress end-to-end tests in Gitlab CI. Itās not at all perfect, but gives me more confidence when testing with new Nextcloud releases. There seems to be no documentation on end-to-end tests, even though ā in my opinion ā they are much more useful for UI-heavy Nextcloud apps than unit tests. We need documentation on how to write end-to-end tests and how to set up CI for them.
- PHP stubs and editor Intellisense ā Iāve started using Intelephense for Visual Studio Code and included my local Nextcloud git, as well as some stubs by @ChristophWurst, that can be found in composer, in its config. See this post. We urgently need documentation on how to set up most used editors for development. Iād never have guessed some deprecations or specific call signatures that I now get to see with this setup.
- PHP API ā This brings me to my last point: There appears to be no public roadmap for PHP APIs. I can never be sure what the latest and greatest way of doing things is (like loading assets, loading the current user object, routing, query building etc.), because things change all the time (with most of the legacy stuff staying around for a while, to be fair). The way I adapted to this, is to browse the core apps every once in a while to figure out what they changed. Also I subscribe to the Github issues on the server repository that mention breaking changes in each release. Finally, Iāve added a step to my CI tests that dump the nextcloud.log file to see if I missed any deprecation warnings or obscure errors during development. To fix this, we urgently need good documentation for all PHP APIs and some info on when theyāre no longer recommended to be used and what to use instead and how to use it.
- Missing basics ā Part of my problem is that I donāt understand Symfony very well, which I think most Nextcloud APIs are based on? The developer documentation should link to the Symfony documentation or any other 3rd-party library used where necessary and explain common concepts of that library (like naming, mappers, available super classes etc).
Nextcloud, the company, and developer relations
Iād be happy to help with this effort, but I also see Nextcloud as a company in (deep) debt here, because only they have the resources to hire someone like you to take a first shot at this. And since the whole ecosystem profits from good apps, I think there should be incentive to invest much more into developer relations, but I can remember that we mentioned this avenue to Frank a few years ago and he didnāt seem impressed ā¦ so thereās that
Letās look around for good examples
Lastly, I want to suggest to not re-invent the wheel. We should take a look at other projects that have a successful (and diverse in terms of levels, from beginner to expert) app developer community. Iām not saying itās a prime example, but take a look at how good the WordPress documentation has gotten. It has examples on almost all methods, hooks, actions etc. It also has guides now to cover basic concepts and those guides are exhaustive.
I know the Nextcloud developer documentation has guides too, and kudos to the person who wrote them, but theyāre really only scratching the surface if weāre being honest.
This got much longer than I intended ā hope itās useful regardless.
ā Thomas