Improve usability of created/created_by/set_at/set_by in the publishing API ?

[bradenmacdonald]

• If you call create_publishable_entity, specifying created (timestamp) and created_by is mandatory, and gets set directly on the new PublishableEntity model.
  • If you do this within a bulk_draft_changes_for/DraftChangeLogContext, the changed_at/changed_by from the context does not override the created/created_by specified on create_publishable_entity(). Note also that simply creating an entity without any version does not affect the changelog nor create a change log record (expected).
• If you call create_publishable_entity_version, specifying created (timestamp) and created_by is mandatory.
  • If you do this within a bulk_draft_changes_for/DraftChangeLogContext, the changed_at/changed_by from the context overrides the the created/created_by specified here. But you still have to specify it.
• If you call soft_delete_draft, specifying deleted_by (user id) is optional, and specifying a timestamp is not possible.
  • If you do this within a bulk_draft_changes_for/DraftChangeLogContext, the changed_at/changed_by from the context overrides the the deleted_by specified here.
• If you call reset_drafts_to_published, specifying reset_at/reset_by is optional.
  • If you do this within a bulk_draft_changes_for/DraftChangeLogContext, the changed_at/changed_by from the context overrides them, and they are ignored.
• If you call set_draft_version directly, specifying set_at/set_by is optional.
  • If you do this within a bulk_draft_changes_for/DraftChangeLogContext, the reset_at/reset_by from the context overrides them, and they are ignored.

The Containers and Components APIs also often accept/require created/created_by arguments, which are sometimes mandatory and sometimes optional, and follow the same patterns as above.

The create_x_and_version APIs are generally structured so that the created timestamp is mandatory, passing it through the layers so that the X and XVersion both have the same created timestamp. The created_by is more likely to be optional because it will still be consistently None even if omitted at the top level.

When the user ID is optional, the API cannot detect/model the difference between "I forgot to specify the user" and "this is a system action with no associated user" - both use user_id=None.

Names of the timestamp variable: changed_at, created, reset_at, set_at

Names of the user ID variable: changed_by, created_by, reset_by, set_by, deleted_by

[bradenmacdonald]

Suggestion: make all the parameters optional, but throw an error if they are not specified when used outside of bulk_draft_changes_for. Make the default value of the user _by parameters a sentinel value like AUTO (get from the bulk context) so that user_id=None is always a very explicit choice.