[meta] Improve DX of entity defining (if you want a UI)

This past week/weekend, I went through the process of defining a D8 content entity type with bundles (because I'm working on the d8 update of my programming with Drupal book), and with a UI that allows you to do CRUD on both the entity objects and bundles.

Keep in mind that I'm kind of an outsider to entity defining in D8 -- I haven't been very involved in building the existing core system (which I think gradually evolved) or the existing core entities.

I used the existing entities as a model... but it took me hours of debugging to get it all working, and the code and routes I ended up with were still not all that great at the end of it all. Maybe there were things I didn't understand (where we need better documentation), and maybe it's just that the DX needs improvement?

Anyway, defining a UI for entities seems very complex. Between the main entity and the config entity for the bundles, this involved defining:

• 8 routes with placeholders
• Various menu links, action links, and task links
• A theme hook, Twig template, and preprocess function for displaying the content entity
• 9 classes and interfaces for the entities, their forms, and the config list controller
• A config schema for the bundle entity
• A few methods in a Controller outside the entity space
• - A URI callback function [no longer necessary]
• A permission in hook_permission()
• Views integration for the content entity, assuming you want to use Views to make an admin page similar to admin/content (I didn't actually yet even do that); then you'd want to also export your view as config.
• And I just found out that if I am using SQL storage and want it to have decent indexes, I also need to define a storage controller class; see #2326949: Move entity-type-specific schema information from the storage class to a schema handler

This process seems overly complicated, and part of the problem was that I pretty much had to do all of the above steps before I could test anything in the UI.

Here are some things that occurred to me during this process, that I thought could be improved:

• [A] I am not sure why I needed to build an editing form for the config entity, when I think it could have been built from the config schema. Could we have a standard entity form class that we could use that would do that?

  [Berdir: "Sure, that would be great" [just hasn't been done yet]

• [B] I am not sure why I needed to define an editing form for the content entity, when all it does is put up a field for the title/label, which should be pretty obvious from some other methods on the entity class etc. Could we have a standard entity form class that would do that?

  [Berdir: (paraphrasing) you can use widgets for the form elements... see example links in comment #2]

  Related issues:
  #2312133: Make EntityForm::save() save the entity
  #2230637: Create a Language field widget and the related formatter
  #2226493: Apply formatters and widgets to Node base fields

• [C] The delete confirm forms... For the config entity, that maybe had to be custom, because you have to figure out what to do if the bundle is deleted and there are entities defined in that bundle. But I don't see why the main entity delete needed its own custom form. Could we have a standard one?

  [Berdir, paraphrasing: Existing entity types have small differences in wording, so it's hard to standardize.]

• [SORRY, there is no (d)]
• [E] Routes and menu links... These could be made totally standard, given a path prefix. For instance if I said the prefix was "myentity" for the content entity, then standard routes could be made for myentity/[ID]/[op], where [op] is delete or edit or missing for the view page. For the config entity, you just need edit/delete, even easier.

  [Berdir, paraphrasing: Existing entity types have small differences, so it's hard to standardize.]

  [timplunkett, paraphrasing: Making these automatic would make it harder to understand. Right now at least all the routes for a module can be found in one place.]

  [jhodgdon: Maybe it could be made easier in the routing.yml files, something like:

  my.route.name:
    _entity_route: myentity 
    _route_type: edit
  

  ]

  Related issues:
  - #2259445: Entity Resource unification
  - #2285413: [Meta] Standardize entity route names
  - #2089757: Auto generate routing entries for entities based on an 'admin_path' and 'admin_permission' annotation
  - #2316949: Title setting in EntityViewController::view() is not working right

• [F] Theming - for the content entity, really I don't know why I had to define an entity theme for my entity type, Couldn't there be a fallback? All it does is maybe put up the title and let Field module do the rest. Couldn't that be standardized?

  [Berdir, paraphrasing: Existing entity types have small differences, so it's hard to standardize.]

  Related issues:
  - #2301245: Entity system invokes non-existing theme hooks: "Theme hook $entity_type_id not found."
  - #2270883: Automatically add theme hook suggestions for all entity types
  - #2023571: Support preprocessing in EntityViewBuilder

• [G] Config entity list builder - I think this could be standardized?

  [Berdir, paraphrasing: Existing entity types have small differences, so it's hard to standardize.]

• [H] Views integration -- I didn't actually do this yet but it seems like that could probably be mostly standardized too?

  This is actually being done on:
  - #1740492: Implement a default entity views data handler

• [I] Storage -- it seems like specification of NOT NULL for indexing efficiency could be done as part of the entity class's baseFieldDefinition() method? And maybe specification of what fields need indexes could be also on the base entity class? See #2326949-10: Move entity-type-specific schema information from the storage class to a schema handler.