Cross-posted from http://randyfay.com/content/examples-project-split-it

It's time to re-evaluate the strategy and goals of the Examples Project on Drupal.org.

The project had its origin as documentation examples, but they were buried in an obscure place in the CVS tree and had no executable format. During the D7 cycle we dusted them off, added tests, and put them into a maintainable place where they'd be automatically tested and were maintainable. Loads and loads of examples were added, and lots of things were improved. Lots of people put hundreds of hours into this, and the entire community appreciates it.

However, I think it's time to re-evaluate the maintenance of this project, and to talk about how it should be structured long-term. I personally am not committed to maintaining the new 8.x examples and changes that need to be made, and other maintainers have not been able to keep up either. The result is that testing on the 8.x branch has been broken (theming and render, contextual links) for nearly six months. And all that is before the real changes in 8.x core kick in.

I propose that we:

  • Branch off of the current 8.x-1.x branch a copy, and then remove the 8.x code from the project. To date, I think it has received only copycat (cherry-pick) commits, and probably some of those have been missed.
  • Separate the various examples into separate projects (git repositories). The master Examples project could continue as a reference page for the other examples.
  • Seek individual maintainers for each example module (or theme, or profile).
  • Move relevant open issues into the new projects.

As a result, we'd be able to support projects that are not core, a common request which has been denied many times because there are limits to what can go into one project. We would also be able to branch out into themes and profiles, which was not possible within the one-module structure.

I believe that this would distribute the overall maintainership load much more sustainably, and would permit a better approach to newer 8.x examples.

Consequences of this?

  • Changes to api.drupal.org will be required to pull in the new separate examples projects.
  • d7.drupalexamples.info and d6.drupalexamples.info will have to be slightly reworked, and maintenance of them will be a bit harder
  • People may be confused that everything's not in one place. I suppose we could make a tool that would bring them all together for download.

Comments

rfay’s picture

Issue summary: View changes
lathan’s picture

+1 for the shift.

I know of one other that did a really good job of providing a kick start for creating entities... http://drupal.org/project/model would be awesome to see more examples with more of the contrib space as well, if this enables that then i am all in.

PS: I was looking for an Entity API example from the examples project but that was shut down.

rfay’s picture

@jucallme I think model is a great example of why splitting would be great. Of course, the problem with all of this is that the actual result depends on the quality of maintainership, and although model has great maintainership, that doesn't guarantee it for all examples. And we all know that quality will vary with interest and available time.

Mile23’s picture

I wrote a whole long thing about why there shouldn't be a split, but then realized I had fallen into this trap already. :-)

http://drupal.org/sandbox/Mile23/1289524

The problem then becomes: How do people find these projects? Should there be a curated 'Examples' or 'sample code' tag for projects? Will there be someone to flip a switch that says, "Include this in api.drupal.org crawl"?

rfay’s picture

@Mile23, I think the Examples project should live on as an index project, pointing people to the examples. And there is a taxonomy term (finally) for examples. But a curated project page is better.

cweagans’s picture

Personally, I don't like this idea. I like being able to have somebody download the examples project and have so much available to them right away. If examples is broken up into separate contrib modules, I don't think it'll be as useful and will lead to duplication of examples, since there's not really one canonical place to get things done on the project.

tl;dr: -1

Dave Reid’s picture

I'm also kind of against splitting up the Examples project, except for contrib examples, which I believe generally live better off bundled with their respective contrib modules with the 'package = Examples' in their .info.

sreynen’s picture

I suppose we could make a tool that would bring them all together for download.

Don't we already have that tool in the install profile packager? An install profile that provided an example of what an install profile should look like while also packaging and enabling all the examples modules for demonstration sounds good to me, whether or not the modules are actually split up.

drumm’s picture

I want API.drupal.org to get all projects eventually, so don't consider that a blocker. It is a bit cumbersome, so you may earn admin access to the site if there are lots of and/or frequent changes. That will improve in the future, but a d7 upgrade is higher priority.

Otherwise, I don't have an opinion on this issue.

clemens.tolboom’s picture

I don't like splitting the examples for downloaders. But from a developer perspective it maybe better to focus on an example bundle like modules/themes/profiles.

A solution could be using git subtree for maintaining the ease of use for downloaders and still have separate projects for developing. This is a little similar to symfony on git hub having readonly component repos but in reverse.

I'm not sure this works for the API workflow tools on d.o

(@helmo did a lot off work on his https://github.com/helmo/git-subtree)

awolfey’s picture

I agree with Dave Reid in #6. drush dl examples makes life easy. If that ease could be duplicated with example modules living separately somewhere, then I think no harm is done by splitting.

lathan’s picture

Title: Get more active maintainers and allow a greater diversity of examples » Split Examples project into separate projects, one per module.

@Dave Reid do you know how difficult it can be to get examples from some maintainers? Most tend to shrug you off with the I'm to busy line....

But that is not the point i would love if there were more examples of contrib and core... right now I do tend to think the structure with the examples project is to ridged to allow it to expand to include some key contrib modules as the guideline has been that examples only shows core examples and nothing beyond that.

Dave Reid’s picture

I don't see anywhere in this issue where we're forcing maintainers to write examples. I'm probably one of the busiest maintainers and I had time to write the token examples, so I don't know where that's coming from.

rfay’s picture

@Dave Reid, using yourself as a prototype of ordinary maintainers is simply not reasonable. None of us know how you do what you do, and we love you for what you do. But nobody will ever keep up with what you do.

The reality is that we can't force devs to do examples, and most of the time they do an inadequate job. Allowing different maintainers to "adopt" specific examples (as we could do better... maybe... by splitting the module) has the advantage of splitting up the leadership.

Although I've tried repeatedly to get people to take leadership for the various components of examples, it's unusual for any of the many committers besides me to commit something. My theory is that if maintainers have their name on the node, they'll be more willing.

jhodgdon’s picture

Breaking Examples up into smaller projects, if the maintainers think it will be better, seems kind of OK.

But only if there can be one central place where people can go to download the whole Examples set in a zip. Could there, for instance, be an Examples install profile, which could (I think?) then be packaged as a distribution with all the examples automatically included? It seems like that would not be too hard for someone to maintain -- they would just need to maintain a project page linking to all the individual modules, and a manifest somewhere in the git repository, right? [I'm a bit hazy on install profiles...]

cweagans’s picture

Just because we can use the install profile packaging thingy doesn't mean that we should. Examples.module is not an install profile. It's a collection of modules. I don't want to have to download an install profile to have access to all of the examples code in one place.

jhodgdon’s picture

Agreed... So is there another way to package up a group of modules, themes, and install profiles into one big zip, so that people not familiar with the command line and drush can download them? It would be sad if we made it a lot harder for the very people who might most need the Examples to download them.

cweagans’s picture

Title: Split Examples project into separate projects, one per module. » Get more people involved with maintenance

I don't think we should split them. If I'm reading rfay's comment correctly, he's thinking that splitting them will lead to more accountability and active maintenance. I don't think that's the case. Examples is fairly well maintained right now, but I understand that rfay is doing most of that work. The thing is, if rfay goes away, and we split examples into a bunch of smaller projects, then we have a really wide, shallow pile of unmaintained modules, rather than a tall pile of unmaintained modules. It's half dozen in one hand and six in the other.

If I'm reading the last paragraph of #13 correctly, the real problem to solve here is to figure out what needs to happen to get other people actively involved with this project, and splitting the module up is one possible solution. So I'm going to be bold and change the title - if you disagree with this, feel free to change it back.

As an aside, comments 11-13 are totally off topic. Examples.module is not about contrib examples. It's about core. If you want examples for your favorite contrib module, then write them! Don't try to force the maintainer to do so. rfay did just that with the ctools examples (which are awesome, btw).

moshe weitzman’s picture

Can we discuss alternatives here? I'd be open to adding an examples directory to core and put this stuff there. Thats the best way to keep up with 8.x.

cweagans’s picture

I would *love* to move examples into core, especially if we can do the same with 7.x. Being able to download Drupal with example code prepackaged would be a very very nice thing, IMO.

rfay’s picture

I would love to see Examples in core as well. However, it doesn't really make sense to be part of the core package. It's aimed only at developers. And the examples would pollute the modules page unless we added some kind of "show examples" button or something.

What I'd really like to see is Examples *considered* and maintained as part of core, with examples maintained along with core features, and required maintenance.

rfay’s picture

Title: Get more people involved with maintenance » Get more active maintainers and allow a greater diversity of examples

I just opened #1518272: Remove/archive 8.x-1.x and start over, bringing in only newly ported or created modules because it was one of the issues I was trying to solve here... but not sure this one will fly.

Re-titling, because this issue isn't just about "more people involved". Splitting the module would distribute ownership, hopefully making it more sustainable, and it would also free us from the "core examples only" rule that we imposed long ago just to do *something* with scope.

jhodgdon’s picture

RE #20 - I don't think the examples would have to appear on the Modules page or that they would pollute core at all. Why couldn't there be a top-level "examples" directory in Drupal? The Modules page wouln't look there, and if someone actually wanted to enable a sample module to try it out, they could just move/copy it into their sites/all/modules and go from there.

Dave Reid’s picture

Yeah I definitely didn't mean to say that I'm a typical maintainer *at all*, but I guess even though I'm spread so thin, I still come back to my things eventually which seems to be a minority as well.

cweagans’s picture

Re #21: I think there's a lot of value in having "core examples only" for this project. IMO, for contrib examples, they should be in http://drupal.org/project/examples_contrib or included with the modules that that are setting an example for.

There's like a gazillion maintainers on this project, so the number of people with the ability to help with this project is not the question. It's a matter of getting them engaged/involved and doing things with the project. Distributing the ownership by splitting the modules really isn't going to help anything :/

quicksketch’s picture

I'm also of the opinion that the single-project approach is a better learning tool than separate projects. Being able to go through the example modules one at a time is a great way to learn how certain things work in Drupal. I've seen more than one person start with the examples module to learn a particular topic and then immediately say, "OH! There's an example for X? I've always wanted to do X!", so the single project approach introduces users to concepts that they probably wouldn't have discovered had they been told to download the "Y example" module. I love the examples module as a learning tool, splitting it up into multiple projects introduces more set up before learning can begin or makes discovery/progressive learning less likely.

andypost’s picture

Title: Split Examples project into separate projects, one per module. » Get more active maintainers and allow a greater diversity of examples

I think there's should be a examples distribution! The only purpose of this to learn devs so please leave core clean as possible.
D.O infra now allows to download distribution as a zip so no actual reason to maintain all examples in one place.
This distribution could be supported by training/learning centres or teams also this could help to invite more maintainers.

EDIT: I does not like examples pre-packaged with modules this makes harder to watch changes in actual working code (more commits to track) Much better to have a link on project page (in Resources or Development blocks)

Mile23’s picture

@rfay: "Although I've tried repeatedly to get people to take leadership for the various components of examples, it's unusual for any of the many committers besides me to commit something. My theory is that if maintainers have their name on the node, they'll be more willing."

I've been reticent due to novice-hood and fear of destroying the whole thing due to fumblefingers. I can take this on to a greater degree, maybe even without much hand-holding. :-)

Senpai’s picture

"Separate the various examples into separate projects (git repositories)" No, No, No. Having this stuff as a single project in a single repository is the *only* way the general public can make use of it. Sure, split up the various things into "sub-modules" or groups of module examples within the parent project, but it absolutely must be hosted in a singular location with a single set of version-control instructions. Split these 'instructions' up into multiple repos, and you're effectively selling each chapter of your car's repair manual from a separate auto parts store.

"Seek individual maintainers for each example module, theme, and profile." Yes, this is mandatory, and necessary, and I believe it's not only possible but also beneficiary to have 100 committers listed on the Examples project page. :)

rfay’s picture

Per #18 I opened a core issue suggesting we move Examples into core:
#1532612: Move Examples Project into Drupal core

Walt Haas’s picture

Sorry I'm so late to the party. I've benefited a lot from the examples project, and developed some examples of my own in the process of learning how fields work. Looking at how the current Examples project is organized I didn't see a straightforward way to add my examples to the project so created and submitted a sandbox project:

git clone --recursive --branch 7.x-1.0-rc1 http://git.drupal.org/sandbox/WaltHaas/1466474.git fieldexamples

for promotion to full project and was referred here.

Personally, I am a fan of small kernels that can be easily added to, for the reason that in many cases you don't need more than the basics, and when you do, the additional things you need are different for every site. So I don't like the thought of pushing examples into core. In fact there are some things I'd like to see removed from core, such as 'book' and 'blog'. But that's another discussion.

I do like the idea of more flexible rules for the examples project. In particular, I'd like to see an organization of modules and sub-modules such as in the organization of my sandbox project, above. This allows examples for contributed modules to be added without requiring that every user download and install every contrib module referred to in an example. I think this organization would make it easier to add contributed examples. The proliferation of projects providing examples for contributed modules suggests that there is a lot of opportunity in this area.

I'd also like to see use of the Advanced Help module for documentation of examples. This would give more opportunity to cross-reference between examples where that's appropriate. In many cases it's very helpful to see how contributed modules interact, for example, Entity API and Views. I didn't use Advanced Help for my sandbox project because it seemed like overkill, but for a larger collection of examples I believe it would be justified.

-- Walt

rfay’s picture

Hi Walt -

The "field example" would be the example to improve, if I understand you. Please open a new issue and provide a patch to improve it, or start a discussion about what you need.

Discussions about how to organize the Examples project, advanced help, etc., also belong in other issues.

Walt Haas’s picture

OK let me back up a bit ... I've learned a lot from various parts of the examples project, thanks! When I started learning how fields work, I found that the field_example module was too complicated for me to absorb as a first step, in other words I had the same reaction as in comment #2 to this issue. So I thought about ways to make simpler examples.

I don't see a way to add a simpler example to the existing field_example as it is now organized. The situation with fields is different from the situation with for example forms, where you can have multiple forms in a single module. If I tried to add simpler fields to the existing field_example module, I'm afraid the result would be harder to understand not easier. So if I submit a patch it would need to create a sub-directory of examples/field_examples to hold my simpler examples and the existing example separately. Would that be OK with you?

Also in my description I mention how fields interact with the views module, although neither of my examples requires views. This seems to me an important thing to document to help the student.

Should I open a feature request issue to discuss my ideas about a possible new organization for examples?

-- Walt

rfay’s picture

@Walt Haas, I was trying to gently explain to you not to hijack an issue but to open a new one. Do I need to use upper case letters?

rfay’s picture

Status: Active » Closed (won't fix)

I'm closing this one; it got no traction.

Probably the only current "live" proposal is #1532612: Move Examples Project into Drupal core

rfay’s picture

Issue summary: View changes

Added the fact that d7.drupalexamples.info will have to be reworked.