Changes to documentation handling

Hi fellow developers,

after some discussions here and there, we decided to change the approach how we collect the information for app developers and maintainers.

History

In the further past we had issues where we collected critical changes that affect app developers

With Nextcloud 25 we tried to change the approach in order to improve the coverage, so it includes more things affecting app developers, not only breaking changes, but it seems that this was not communicated properly and nothing is worse than half completed “upgrade” documentation, that gives you the feeling you upgraded everything.

But the recent attempts showed that sometimes this was seen as enough documentation, while the idea was basically to have a changelog with links to pull requests and updated documentations kind of thing.
Also it is quite painful to copy that information over to the actual documentation that app developers then read later on, e.g.
https://docs.nextcloud.com/server/latest/developer_manual/app_publishing_maintenance/app_upgrade_guide/upgrade_to_26.html
Special thanks to Christoph who kept this running and up for so long. :bowing_man:

New

So to keep our life easier and improve the documentation and experience for app developers and ourselves we change the flow as follows:

  • From Nextcloud 28 onwards there will no longer be a “Changes for developers & admins for Nextcloud X” GitHub ticket
  • Instead all affected changes need to be sent as a Pull Request directly on the documentation repository to the upgrade_to_X.rst file
  • This affects especially but not exclusively: (Changes = Additions, Removals or Modifications)
    • Changes to dependencies: Major bump of Doctrine (our database system), moving from Swiftmailer to SymfonyMailer, global Bootstrap removal, …
    • Changes to public API aka. OCP: lib/public/
    • Changes to recommended or state of the art abstract/base classes, e.g. core/Command, core/Controller, core/templates, …
    • Changes to “default” initial state or capabilities
    • Changes to OCS APIs
    • Changes to index.php routes that are known to be used or could be used by others, e.g. Avatars, index.php APIs, etc.
    • Changes to an Event (being it PHP or JS)
    • Changes to public or state of the art Javascript functionality
    • Changes to “global” CSS

In case of doubt write the documentation, ask another developer for confirmation or ask yourself:
“If someone else did this change, would I like to know or should I know about it to maintain my assigned apps or any apps I’m aware of?”.
If the answer is Yes or Maybe, documentation should be written.

7 Likes