Problem/Motivation
The Examples for Developers project helps drupal developers to quickly see and understands how drupal core APIs work; maintaining several submodules that show how to interact with each API subset.
This (meta)issue is about moving every submodule to drupal core.
Why adding it to core?
- To ship an functional example of how to use every API in core for developers(also improve visibility of those helpful examples).
- To help maintaining the examples, which are useful, but with not enough maintainers.
Other considerations
- Examples project submodules should be treated as documentation inside core.
- There was some concern about maintaining example submodules tests working while making major changes in core, but that was solved by this propossal: "Just remove examples or disable tests at the beginning of the cycle, and then make sure they get done at the end. The reality is they could be added in one at a time just like we're talking about doing now for D8.".
- Tests(and test helper modules) and examples modules are different, they have different targets. There is no code duplication — or much rather, there should not be code duplication, since all test modules should contain code that you should NOT consume as examples in any way.
Proposed resolution
In order to get every examples project submodule into core, we can follow an iterative process of 'staging' submodules to the Examples project, and then eventually creating a ticket for inclusion in core.
The process might work like this:
- Improve the example module(based on some reviews in this issue, it seems like it should be needed). Examples should demonstrate best practices in formatting and documentation.
- Port to D8
- Review with coder
- Make sure the documentation is clear, well-written, and follows our documentation standards on http://drupal.org/node/1354
- Add it to 8.x-1.x branch on examples project
- Open an issue for inclusion in core("Add example xyz to core")
Remaining tasks
Some work has begun here:
📌
[meta] Port examples (including submodules) to D9.4+
Active
- Propose a list of the new API subsets which in D8, so we can have an example for each of them.
- Port main examples and add them to core(list based on webchick analysis): block_example, dbtng_example, entity_example, menu_example, nodeapi_example, page_example, theming_example.
- Port the rest of examples and add them to core.
- Decide where example projects will live inside core: see alternatives at comment 81
User interface changes
None.
API changes
Examples project uses @defgroup/@ingroup to define an 'examples' group and a child group per module. We will need to discover whether this causes a problem for api.drupal.org's group organization.
Related Issues
📌
[meta] Port examples (including submodules) to D9.4+
Active
Original report by rfay
Over in
#1516840: Get more active maintainers and allow a greater diversity of examples →
I proposed breaking Examples up into separate modules so that more maintainers might take full ownership and maintain the various modules. But so far, that hasn't gone very well. I'd say the majority is against.
In
#1516840-18: Get more active maintainers and allow a greater diversity of examples →
, though, @moshe suggested that it's worth considering moving Examples into core. This would have a number of advantages both for the examples and for core itself:
- Core changes that broke an example would be shown in the automated test process. This could result in a much earlier understanding of a core shift.
- Likewise, API changes would have to be reflected immediately in Examples changes.
- Example modules could be used by core tests as "Mock modules", so fewer of those mock modules would be required.
- A culture of creating and maintaining examples along with new code would be great for the community, resulting in major learning gains in new releases. In reality, every new API *should* have maintained example code, by policy, IMO.
How could we do this?
- Create a checkbox on the modules page that would show or hide example modules (with them hidden by default).
- Put the example modules in their own "examples" directory, and perhaps not in the regular core/modules. (Perhaps we wouldn't have to do this.)