Usage statistics for distributions

This issue has been reviewed/updated according to http://drupal.org/node/1204344 and is ready for someone to work on.

Related details from a recent discussion on this topic, Oct/Nov 2011, from #1314124: [META] Improve installation profile listing on Drupal.org, comments #5 to #9:

[greggles] (...) Do we have the data for most active and most installed? I think OA is installed on 10,000+ sites but when sorting distros by most installed it doesn't show up due to limitations of usage stats. commons_release is on 1,000+ sites but also doesn't show in the top of the main list. Basically I guess these stats won't be accurate until we solve the "package profiles from d.o" portion. (...)

[webchick] We only have data for most installed for D7 distros, unfortunately, since before then they did not have .info files and did not ping updates.drupal.org. (...)

[greggles] There is a way to track usage for 6.x: http://drupal.org/project/usage/hyperlocalnews - if the distribution put its feature/support modules inside the profile then it reports usage in a way that works. (...)

[webchick] Hm. Apparently not too many know of that hack (...)

[batsonjay] (...) 3. Module counting. Let me propose a way to count modules. (You may, or may not like it.) With Commons, we struggled with how / where to list it on d.o. We initially thought /project/commons, but because we include CKeditor with the distro, we can't build it on d.o, so we couldn't really post the full download there. We added it to the install-profiles listing, but this wasn't an obvious place to get long-term visibility.
Simultaneously, we also struggled with how to do update notifications, since there are version dependencies (e.g. the latest version of any given module might not be one that works with Commons).
To resolve both problems, we created the commons_update module. It's mostly a no-op module itself, but it accomplishes the normal module usage reporting back (assuming phoning home is enabled for the site), and we can also use it to trigger update notifications (by overriding what Commons looks for in updates, and ONLY looking for the commons_update module, burying all the rest).
So one way to get normal reporting is to require distros that want counted to contain an equivalent distro_update module.

It seems greggles was referring to this other discussion, Aug/Sep 2010, from #779476: Remove commit restrictions for installation profiles, comments #10 to #14 (and about commons_release, it's a module, so that's the reason it doesn't appear in the install profiles listing):

[greggles] Currently we don't/can't track usage of installation profiles - http://drupal.org/project/usage/uberdrupal - does this change affect that? What about update module letting people know that a module is out of date if that module is placed inside a profile?

[dww] Currently we don't/can't track usage of installation profiles - http://drupal.org/project/usage/uberdrupal - does this change affect that?
Not directly, no. We should open a separate issue to discuss this I think. It's also related to #509398: Install profiles should be modules with full access to the Drupal API and all it entails(.install files, dependencies, update_x).
What about update module letting people know that a module is out of date if that module is placed inside a profile?
At first I thought you were asking about modules packaged with an install profile, and there are two ways "update status" handles that:
A) Update status itself on installed sites works fine to tell you if any real module projects are out of date, just like always
B) Project module on d.o gives you update-status-like info on release nodes of distributions, e.g.: http://drupal.org/node/869134
However, you're talking about the modules *committed* to the install profile directory directly (as per this issue). I actually don't know if that case is handled correctly by update status. It's possible that all the plumbing I put in place magically Just Works(tm) for this. Someone would have to test it. There *is* a release history feed, even for install profiles:
http://updates.drupal.org/release-history/uberdrupal/6.x
And, the packaging script does its .info file magic, even for install profiles. So, if a module is included in an install profile, the .info file *should* get the right meta data to point update_status at the above feed and in theory, it all works... At least the update_status part of it.
However, if the profile reports there's a newer version, it's not very easy it is to upgrade. :( I guess you can just re-download the whole package and install it in place. However, there's no equivalent to update.php to handle changes between versions of the profile. So, things that changed in .profile itself aren't going to be upgraded/reconfigured/reinstall and you'll be in a slightly weird state -- unless of course the profile maintainer goes out of their way to handle these cases in their profile's module's .install file with hook_update_N() implementations. This is part of what makes install profiles tricky. It's all sort of a can of worms.

[alex_b] However, if the profile reports there's a newer version, it's not very easy it is to upgrade
I recommend keeping the actual profile to the absolute minimum, that is basically installing modules, enabling a theme. All other settings should be captured in Features modules. Thus the entire module infrastructure can be used to manage change.

[greggles] (...) http://drupal.org/project/usage/hyperlocalnews shows that yes, it does count usage if you have a module inside a profile.
My admin/reports/updates page shows, however, that the update information for modules inside of profiles doesn't currently work.

I think basonjay was referring to the Commons Release Updater module, used until Commons 6.x-2.3. See #1335870: Remove Commons_release from Commons. They say, in the commons_release project page:

This project is now deprecated. As of Commons 2.4, Commons sites report usage and check update status via the Drupal.org Commons project.

From Commons 2.4 Release notes:

Commons_release module is deprecated
Historically, Commons informed site administrators about new version of Commons or contributed Drupal modules by way of the Commons release module. Beginning with version 2.4, the Commons release module is disabled. Instead, use the Update status information on your Commons site at http://[site_URL]/admin/reports/updates to let you know when new versions of Commons or contributed modules are available.

Naturally, the commons_release module had an .info file. On the other hand, the Commons distribution doesn't seem to be using any .info file in the profile folder, only drupal_commons.profile; and, additionally, .make files since 6.x-2.4 (drupal_commons.make and commons-dev.make).

See also Usage statistics for Commons Release Updater (since 2011-01-09), and Usage statistics for Commons (since 2012-01-15).

That is, usage statistics seem to be working now for Commons, a D6 distribution, without need for a distro-specific module or an .info file.

How is this working? Is it related in some way to the new drupal_commons.make file?

Well, it's true that I would have written these missing docs directly, as I've done in other cases, if I had all the necessary data. That's why the issue summary says:

Proposed resolution

Find out what exactly distribution maintainers should do in order to obtain usage statistics for Drupal 6 and Drupal 7 versions, and document it.

In fact I'm asking for assistance on some technical details about usage statistics for distributions, in order to write this documentation (others or myself).

For example, as explained above, details are needed on how usage statistics are working now for Commons, a D6 distribution, without need for an .info file or an already removed distro-specific module (since two weeks ago). This new development seems to have important implications for all distributions, I think.

Ah, for D6, custom modules or features committed directly into the profile directory, with their .info files modified by the drupal.org packaging script to point Update Status core module to the profile/distribution project. That's really interesting, thanks dww.

A problem with distributions could be the update core module being frequently disabled. For example, from the Open Atrium documentation:

Security Updates
Drupal core includes a module that is enabled on many installations called "Update Status". This module checks against drupal.org periodically to see if new versions of installed modules are available. If there is a new version, and particularly if the new version is a security release your site will alert you to the new version of the module. It is not recommended to download and install these updates outside of the normal Open Atrium releases.

This is similar to what batsonjay said in a quote above (#2):

we also struggled with how to do update notifications, since there are version dependencies (e.g. the latest version of any given module might not be one that works with Commons).

However, Update Status (D6) and Update Manager (D7) are necessary for usage stats.

So, a short draft for this documentation (intended for distribution maintainers) could be the following. Please point out any errors or possible improvements:

Usage statistics for distributions

Usage statistics are linked from drupal.org's project and release pages of each distribution, and are the basis for the default Sort by: Most installed search filter on the installation profiles / distributions listing.

To obtain usage statistics on drupal.org, distributions need:

1. Releases of the distribution available on its project at drupal.org, in order to collect release statistics.
2. Core modules Update Status (D6), or Update Manager (D7), enabled. It's advisable to have them enabled by default, for information and stats, with a possible notice -if needed- to use only the compatible updates provided by the distribution maintainers.
3. For Drupal 6 only, because of the lack of .info files for D6 versions of distributions, one or more custom modules such as features should be committed directly to the profile directory, on the Drupal git repository, before the packaging system adds core and contrib. The drupal.org packaging script writes metadata in the .info files of the custom modules or features, telling the Update Status module to query the distribution project at drupal.org for available releases, which triggers usage tracking. For example:
   
   

   ; Information added by drupal.org packaging script on 2012-01-18
   version = "6.x-2.4"
   core = "6.x"
   project = "distribution_name"
   datestamp = "1326924940"
   

For Drupal 6, all items on the list, #1, #2, and #3, are needed.
For Drupal 7, just #1 and #2 are all that is needed for usage statistics.

That's a possible text to review (Usage statistics for distributions, in comment #6).

Also, since the docs section Developing installation profiles in Develop for Drupal is for distro project maintainers, and Distributions in the Site Building Guide is more for users (site builders and administrators), this information seems more useful in the development section. It's a short text, however a new sub-page is probably suitable, given that the rest of sub-pages are different topics.

BTW, probably the Developing installation profiles section should be now, with the current developments at drupal.org, Developing installation profiles and distributions. I'm thinking on updating this title if there is no objection.

I've just added your excellent explanation to item #2 on the list. What you propose for the update_advanced module would be really important and useful for distributions, to have usage stats without confusing users about updates. It's a very suitable solution for this.

How about the following text? If there is not any serious error, we can publish it as it is now, and later anyone can edit and improve the handbook page when new data appear, etc.:

Usage statistics for distributions

Usage statistics are linked from drupal.org's project and release pages of each distribution, and are the basis for the default Sort by: Most installed search filter on the installation profiles / distributions listing.

To obtain usage statistics on drupal.org, distributions need:

1. Releases of the distribution available on its project at drupal.org, in order to collect release statistics.
2. Core modules Update Status (D6), or Update Manager (D7), enabled. It's advisable to have them enabled by default, for information and usage tracking, with a possible notice -if needed- to use only the compatible updates provided by the distribution maintainers.
   Distributions can use hook_update_status_alter() (also in Drupal 6) so that update module can remain enabled but still hide warnings about releases from projects managed by the distribution. That's better than using hook_update_projects_alter() since removing projects from the list at that point would prevent those modules from getting proper usage tracking. It's better for update module to keep fetching info for those, but just not display warnings for new releases.
   This is as well a feature request for the update_advanced contributed module, that would provide an easy to use solution for distributions. The issue is #1425522: Help manage updates for distributions.
3. For Drupal 6 only, because of the lack of .info files for D6 versions of distributions, one or more custom modules such as features should be committed directly to the profile directory, on the Drupal git repository, before the packaging system adds core and contrib. The drupal.org packaging script writes metadata in the .info files of the custom modules or features, telling the Update Status module to query the distribution project at drupal.org for available releases, which triggers usage tracking. For example:
   
   

   ; Information added by drupal.org packaging script on 2012-01-18
   version = "6.x-2.4"
   core = "6.x"
   project = "distribution_name"
   datestamp = "1326924940"
   

For Drupal 6, all items on the list, #1, #2, and #3, are needed.
For Drupal 7, just #1 and #2 are all that is needed for usage statistics.

Agree; also English is ESL for me, but style, etc. can be corrected directly on the docs. Or, alternatively, we can consider adding the footer from chx's blog: ;)

discailmre: Me no good type Egnlish fsat. yuo muts not cmplian ' bout the garmar. Site powered by Drupal 6

All right, just added the new handbook page, Usage statistics for distributions. It's in the profile/distro development section; and, as suggested in #7, with the section title updated to "Developing installation profiles and distributions", according to the new naming from #1314124: [META] Improve installation profile listing on Drupal.org and related issues.

So, distributions have usage statistics available, and the docs now explain how, Thanks, dww!