core/USAGE.TXT -- API section talks only about hooks and functions

I am working to triage this issue.

I am working on triaging this issue

Inserted template and formatted jhodgdon's original issue, no UI/API/Model changes seem to be needed for this issue

Thanks @AndrewHD and @jdelvillar01; I take it from your comments that you confirmed this is still an issue with the README (which it is indeed). Updating credit.

As a documentation bugfix, this change is eligible for patch releases.

Have updated the readme.txt of drupal 8.2.x according to your suggestions and also have changed to URL in the bottom section for API. Please give suggestions if any.

Thanks!
~Chirag

Have done more modifications in the paragraph , adding descriptions regarding dependency injection and events and removing the spaces at end-of-line. I hope these changes are valid ones

Thanks!
~Chirag

Thanks for starting on this @chishah92 (and thanks @jhodgdon for reporting the issue).

@alexpott,@webchick, @catch, @effulgentsia, @Cottser, and I discussed this and agreed this could just be considered a normal priority docs bug. The information it is giving is not technically wrong, just... incomplete. (There are definitely other major documentation bugs in core, but this is not one I think.)

From @chishah92's starting patch, it seems to me that a lot of this information is ending up duplicating existing information in the codebase and on the web. The page at https://api.drupal.org/api/drupal is a thorough list of topics, thanks to work by @jhodgdon and others during Drupal 8's development. So, rather than writing up another overview of the APIs, I think it would instead be better to remove the stuff about "hooks and functions" and refer people directly to the extending topic (see https://www.drupal.org/node/1354#link for how). Then, we can update the link to the comprehensive overview on api.d.o as @jhodgdon suggests, and that should provide them with enough information on how to start.

The README.txt was updated in #3192842: Make our README more welcoming by converting it into an "entrypoint" into the Drupal ecosystem and the text here is now in USAGE.txt.

#13. Removed the hooks and functions section and added a link to the extending page, in the same format used in this file. That is, it doesn't use an @link.

Not testing the patch because it is comments.

And I forgot to update the title.

Unassigning because it has been 5 years.

1. Confirmed that https://api.drupal.org/api/drupal/core%21core.api.php/group/extending is a working link that is the landing page for the 'Extending Drupal' topic. That seems much better than trying to duplicate any/all of that in this .txt file.
2. Since the test bot didn't try to run it, confirmed that #21 applies cleanly to the 9.3.x branch (as of commit 8fd69fcce) and 9.2.x (commit 7c4ed97), although not to 8.9.x (doesn't matter, that's security only at this point).
3. #21 is small and clean, removes more lines than it adds, but what it adds is much more useful that what it removes. ;)

Therefore, RTBC!

Thanks,
-Derek

I agree that linking to the API is much more useful here.

What's missing is the bit about

The
flexible hook architecture means that you should never need to directly modify
the files that come with Drupal core to achieve the functionality you want;
instead, functionality modifications take the form of modules.

I do think that somewhere we need to keep something that says don't hack core. Maybe we can add this to the "Overview of extensions and alteration methods for Drupal." section of core.api.php which is how the content that's linked to is generated.

This patch restores the important bit about not hacking core. It does not restore the part and hook and functions because I think this is a high level introductory document. Anyone needing to write code will start reading elsewhere for details of the API.

No interdiff because this is so small.

I know we're restoring the existing text, so maybe this should just go in as-is. But with the shortened version, it repeats "functionality" a lot. How about this?

Drupal contains an extensive API that allows you to add to and modify the
functionality of your site. This means that you should never need to directly
modify the files that come with Drupal core to achieve the behavior you
want; instead, modifications take the form of modules.

@dww, thanks. I think your version is better. I've updated the patch (no interdiff due to size) and started the tests.

Great, thanks! #26 is fixed. No further concerns with #29. Back to RTBC! 🎉

Committed and pushed c304842b8e to 9.4.x and 93f0416955 to 9.3.x. Thanks!