When should the lifecycle switch from experimental to stable?

We only really use this for core modules - in these cases we switch modules to stable once we don't anticipate further blocking issues for them to be fully stable (which can be any time during a core minor release cycle, but obviously they only get released as 'stable' once that minor release hits beta/rc/stable itself).

For contrib modules I personally wouldn't rely on lifecycle for the entire project because that can be communicated with version numbers - alpha/beta/rc etc. However if you had a submodule in a project, and you wanted that to be available but with a warning, then the lifecycle: experimental could work for that in the same way as it does for core.

Should it be documented then that lifecycle should not be set for the top-level module in a contrib project? Should core be changed so that it does not display anything on the status page for the top-level module in a contrib project?

This came up for me in [#search_api_saved_searches]. Until its recent full release, there was a warning on the status page about this module, even when it was beta and the RC.

I feel it should be clearly documented when this should be used and how.

Perhaps info could be added to Creating modules → ? And I found the related Change Record, https://www.drupal.org/node/3215042 → which has details.

Yes, that change record has some information but it is not explicit about when something switches from experimental to stable.

Checking in here and I don't see that any documentation has been updated.

Therefore, I have added a lifecylce section → to document the reply in #2.

I think any further improvements can happen in the documentation and this can be closed.

Concur with #6