Addons: Only some .zips will install

Why is it that if I go to install an add-on from User Preferences > Add-ons > Install from File... and choose a *.ZIP, some add-ons will install, while others will return me to the User Preferences with nothing having happened (as far as I can tell)?

Is there a specific file structure required in the .ZIP? I get many add-ons from GitHub, using the Download Zip button, and even there installation of the actual Zip file only works some of the time.

You can install from zip directly if the zip is either:

• a zipped single .py file

  addon_name.zip
|

• a zipped folder, important that it's not a zip that contains a folder first.

• these will work because the folder structure is at the expected level. The __init__.py is directly inside the zip ("top level").

  addon_name.zip
|
__init__.py


this will also work

  addon_name.zip
|
|
__init__.py

• for instance: this zip will fail, because the add-on folder is nested too deep, there's another folder inside the zip:
• https://github.com/zeffii/TubeTool (this is a link to a branch that first has an extra level of folder nesting)
• Github will generate a zip from that repo that looks like this:

  repository_name.zip
|
repository_name_folder
|
first_folder_in_repo
|

• Can I get a fact check on this? The last one should not fail as the .zip file is extracted into the add-ons folder (as it does in the source code) and the __init__.py file will get picked up by Blender. The system has been this way since Blender 2.6 according to git blame. I structured my add-on like the last one and it works fine... – Coburn Sep 13 '18 at 2:24