Hello everyone,
Last week I sat down with the engineering team leads to reflect on changes we made in the past to the core code that affected app developers after the feedback of @cweiske here.
While we concluded that most of the changes were not reasonably avoidable (some things that broke were things that were not the recommended way of working in the first place, others had to be changed to keep the technology stack up to date), we did conclude that the documentation of such changes and their workarounds is embarrassingly bad - it often doesn’t even exist 
.
For the Nextcloud 26 release we would like to do a good job gathering and documenting the changes that will affect app developers. We want to facilitate this through the following three key procedures:
1. The definition of done will soon include a checkbox for documentation.
This means the development of your feature cannot be considered done if you introduced changes that affect app developers that you did not document.
The team leads will be adjusting the Github templates soon like this one in deck.
2. If you have made a change that affects app developers, you have to report and document the change here.
So the author of the change is responsible and expected to be the author of the documentation.
There are four requirements for this documentation:
It should be written so that app developers understand how to work around the change for their app in a tutorial format
You should write the steps, so you are not allowed to refer to an external site for the steps. You can add an external site as an additional reference but the tutorial should be readable and actionable without browsing to this link.
It has to be carefully written. The author’s name will be added to the final publication so people can reach out to you if they have questions or if something is unclear.
Timeline: the documentation is required to be handed in immediately after merging your PR.
3. The documentation will then be copy-pasted into the developer documentation and on the forum for the first beta release.
These procedures have also been documented in our developer documentation and apply to every developer working on the Nextcloud code.
We hope these steps will improve the experience for everyone!