Clarify theme ZIP file structure for updates #358
Description
The current documentation implicitly assumes that a theme's ZIP file will contain a single root folder and that all theme files will reside within that folder. This is a common and well-known best practice among experienced developers. However, it is not explicitly stated as a hard requirement (or I'm unable to find this requirement in the docs).
This lack of explicit documentation can lead to a specific bug, as demonstrated in the Trac ticket https://core.trac.wordpress.org/ticket/63737. When a user attempts to update a theme via ZIP upload, if the theme's files are at the root of the ZIP archive (instead of being inside a containing folder), a previous failed update attempt (e.g., trying to upload the theme ZIP through the plugin installer) can cause subsequent, correct update attempts to fail. WordPress, in this scenario, creates a new directory (e.g., my-theme-1) instead of overwriting the existing theme folder, breaking the update process.
Proposed Change:
Add a new, clear, and prominent section to the relevant documentation that explicitly states the correct ZIP file structure for themes. This should be added to both developer-facing and user-facing documentation.