[policy, no patch] Mark the help topics module as beta stability

Also it opens time-frame for contrib to start writing help and provide integration to search_api is first priority

+1!

Thank you to everyone who helped get help topics to beta stability and to core committers team for their ongoing support!

+1!

@andypost suggested that we wait until #3075695: Move search_index() and related functions to a service is done to mark this as Beta, but that is an issue in search.module, not help_topics.module -- it updates some code in Help Topics, but also in other modules -- so I think we should not block Help Topics being Beta on that.

+1 to consider it beta, surely it is not blocked on search module clean-up

Here's a walkthrough wearing my "product manager" hat. As a reminder, the old help system looks like this:

Help pages are oriented by module name, which non-user 1 users will rarely if ever see. There's basically no "content author"-facing help at all; so if you're having trouble with using the autocomplete widget on your Blog content, for example, you need to somehow divine that you need to click "Taxonomy" for that. And even if you do manage to get there, it's entirely gobbeldygook aimed at site builders, with language like "You will also need to enable the Create referenced entities if they don't already exist option, and restrict the field to one vocabulary." WAT.

"Tours" sounds like it might be vaguely helpful, but it has... one... entry. That doesn't... actually... seem to link to anything (?!). So. There's that.

So this is our starting point. We can basically only go up from here. ;)

Here's the new help overview page with the Help Topics module enabled:

Hey, wow, this kinda even looks like a REAL Help section! :D Search is prominently featured at the top, there are actual ENGLISH words like "navigation" and "site settings." NICE.

PROBLEM, BETA BLOCKER?: Unfortunately, I can't seem to get that search box to return anything... no matter what I type in there. Even if it's text I'm directly copy/pasting from the help links/text itself:

Note: I'm testing on simplytest.me which is sometimes buggy. So if this is a simplytest.me thing, we can disregard it. But otherwise, I'm unfortunately inclined to call this a beta blocker, because it's a very basic, prominent feature of this module that appears to be absolutely not working.

(Random musing: Are we missing a call to update the search index on hook_install() or something?)

Then we get to the actual help pages themselves, for example:

PROBLEM, MAJOR FOLLOW-UP (if it doesn't already exist) There seem to be discrepancies in style/wording between these pages; there's a lack of a consistent pattern (or unless I'm just missing the pattern). Like some, such as admin/help/topic/core.config_basic (the first screenshot), are more or less a "buffet" of links that show you what you can do. Others, like admin/help/topic/help_topics.help_topic_search (the second screenshot), seem to be step-by-step instructions for accomplishing a task. Ideally, people would have some idea of what kind of help they were going to get prior to clicking into it.

I'm not really worried about this though for beta, because a) once this is in and settled as a feature, "crowd-sourcing" writing these pages is a lot easier (maybe at DrupalCon? :)), and b) we can change this kind of text all the way to RC, I think?

But... there are still a couple of pages that seem to be... stub/blank pages with nothing on them?

This one is particularly bad, because it tells you it's going to tell you about "Defining navigation and URLs" but then... doesn't do that at all. It instead refers you to a "related topic" of "Making your site secure" (which has nothing to do with navigation/URLs), and when you click that you're taken to another stub page which links back to the first. :P

PROBLEM, BETA BLOCKER?: Let's please get rid of these stub-pages, so we can put our best foot forward here.

I have "?s" next to beta blockers above, because my strong preference would be to fix these up before marking beta (or at least before shipping in 8.8.0), and I really hope they're fairly easy to do (at least the last one should be?), however, as mentioned at the beginning of this post, we can really only go up from here, so I would not want to block this module from making into 8.8.0 at all on these concerns.

Also, thanks for all of the obvious work that's gone into this module in the past few months. AMAZING effort. We're almost there!

>Unfortunately, I can't seem to get that search box to return anything... no
>matter what I type in there. Even if it's text I'm directly copy/pasting
>from the help links/text itself:

Yes, this is being discussed extensively in Slack and we are working on this here https://www.drupal.org/project/drupal/issues/3087218.

> ...Let's please get rid of these stub-pages, so we can put our best foot forward here.

This is definitely the plan and myself and @jhodgdon along with other friendly folks in the docs community will be focusing on this next. As in, "help topics gets marked as beta, let's do this now." It has been in the plan for _stable_, not at as a beta blocker thus far. There are multiple issues associated with this effort, which are listed under "Roadmap for Stable" here: https://www.drupal.org/project/drupal/issues/3027054.

Ok then, it looks like the issues I've found already have issues filed for them, and though I'd prefer them both to get fixed much sooner than stable, given the fairly sizable WTF-factor, it seems like the team is on top of it and we won't be shipping with this in production this way, at least...

So removing the product manager review tag + updating the issue summary to indicate sign-off. Thanks a lot. <3

Cross-post. :)

Since this is still tagged "Needs Release Manager Review", maybe I can ask this question here:

Going forward from Beta to Stable, one of the things we really need to do (as noted above) is flesh out the actual Topics.

They should eventually land in other core modules' core/modules/xxx/help_topics directories, or in core/help_topics.

But my question is: can we make commits that fall outside of core/modules/help_topics while we are in the Beta phase, or do we need to put all the topics inside core/modules/help_topics for now and move them out when we get to Stable?

Actually... We may need to not mark this as Beta.

My concern is that we had planned to merge the Help Topics module into the existing Help module as part of the release. That will change a lot of namespaces. Is that a BC break? If so, we may not want to officially "mark this as beta" ... I'm not sure if this case has come up before?

In Slack @xjm brought up a similar case:

So e.g. for Layout Discovery Tim added the classes within the module directory, but used core. prefixed service names so that the machine names would stay the same. Then moved the classes into stable once they were stable (with FM signoff), but kept the ones inside the module as wrappers.

So it sounds like we might need to change some service names before we go to beta? And then once we get Stable, we would leave the classes all there as wrappers?

If all we need to do now is change some service names, we can probably make a quick patch. ...

Re #21, is this something we could achieve between alpha and beta (in the next 2 weeks)? As I'm understanding it (correct me if I'm wrong), we need to have a BC layer that anticipates that we'll be moving things into the help module for stable. Without that BC layer, we can't be "beta".

It sounds like what we need to do ASAP, to get this issue back to RTBC, is:
#3087496: Change prefixes of Help Topics machine names to help and make sure APIs are marked @internal

The other part of making BC classes would be part of the final merge issue.

Adding both to the Roadmap issue.

We are no longer at Beta ready due to #24.

This issue is now the blocker for having all the beta/BC issues done:
#3087496: Change prefixes of Help Topics machine names to help and make sure APIs are marked @internal
If that gets committed, we can put this back to RTBC. Still need release manager review as well.

At larowlan's suggestion, I just created #3087667: Set up class aliases for Help Topics classes and it is also now a blocker for Beta. Should also be a quick fix.

Might have been @xjm's suggestion on #27. Anyway. We currently have two blockers for Beta for Help Topics:
#3087496: Change prefixes of Help Topics machine names to help and make sure APIs are marked @internal -- about a 3-line patch, RTBC
#3087667: Set up class aliases for Help Topics classes -- I made a patch but I have questions about it.

My mistake. We don't want class aliases. So the only blocker is
#3087496: Change prefixes of Help Topics machine names to help and make sure APIs are marked @internal
which is a 4-line patch or so, and RTBC.

That's in, so back to RTBC. Will ping release managers to get final approval needed.

Although possibly delay on #3079810: core/help_topics directory does not work, which is a bug fix whose patch causes a BC break (adds arg to constructor)...

Re #31, #3079810: core/help_topics directory does not work is now fixed.

There was a bit of confusion on #3087667: Set up class aliases for Help Topics classes.

To mark help as beta, we want to ensure that it's not exposing any public API as stable code. I believe this is currently the case.

For marking it stable, we want the bits of the API that should be public, to move into the right namespace, but also ensure that sites that have been running the beta version don't break (i.e. leaving empty subclasses or using class aliases for things that would prevent an easy update from the beta to stable version).

So #3087667: Set up class aliases for Help Topics classes is good (although the patch will need to do the opposite) as a stable blocking follow-up, but simply having the issue open is enough to move help topics to beta stability.

I'm untagging this on the basis that the above couple of paragraphs are correct, but if I've missed something please re-tag and ping me in slack.

xjm set us straight, which is why we did not do #3087667: Set up class aliases for Help Topics classes... So yes:

- Currently (beta), Help Topics is entirely contained within Help Topics, with no bleed into core namespaces and all APIs marked as @internal

- We have a plan for how to move/BC classes and APIs when it's time to be stable. Here's our roadmap issue:
#3027054: Help Topics module roadmap: the path to beta and stable
The "final merge" issue down at the bottom of the issue summary is:
#3037230: Finalize the merge of Help Topics into Help
And it has several sub-issues, including this one that is about BC and moving classes:
#3087499: Merge Help Topics classes into Help with BC layer

So great! I think we have all the approvals for this to go forward!

Thanks everyone! After discussing with @webchick and @catch, it turns out this was down to technicalities on how to restore this. I got some technical help from @alexpott to make sure the composer updates are good. The module is restored now in 8.8 :) Also updated Help Topics to beta in https://www.drupal.org/core/experimental.

Congrats and thanks for your commitment!

WOOOOOOT! Thanks!!!!!

Yay everyone who helped make this happen! Virtual hugs, high-fives, and cupcake emojis for all! Thank you.