Document what constitues the api of forum.module [#2494397]

Problem/Motivation

Over in #2116841: [policy] Decide what the Drupal Public API should be and how to manage it we're talking about how we'll decide what constitutes the Drupal API.
This is the @larowlan's patented less yak, more hack™ approach - lets talk about a concrete implementation and let the policy develop organically.

Proposed resolution

Document what constitutes the api of forum.module as an example of how #2116841: [policy] Decide what the Drupal Public API should be and how to manage it might look

Remaining tasks

Bikeshed
Consensus
Commit

User interface changes

None

API changes

None, other than locking down forum's api.

Comment	File	Size	Author
#4	forum-api.2.patch	21.05 KB	larowlan
#4
	forum-api.1.patch	22.64 KB	larowlan

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

larowlan

🇦🇺🏝.au GMT+10

CreditAttribution: larowlan as a volunteer commented 25 May 2015 at 07:27

Status:

Active

» Needs review

Contentious points in the attached patch - ForumManager protected methods become private.
This means if you want a different implementation of ForumManager, we don't need to worry about future changes from core breaking said implementations.

Comment #2

larowlan

🇦🇺🏝.au GMT+10

CreditAttribution: larowlan as a volunteer commented 25 May 2015 at 07:30

Summary of patch:

all hooks are @internal
all preprocess implementations are @internal
ForumIndexStorageInterface and ForumManagerInterface interfaces are @api
public methods on implementations of said interfaces are @api too
protected methods on ForumManager become private, locking down extension point

Comment #3

Fabianx CreditAttribution: Fabianx as a volunteer and at Tag1 Consulting commented 25 May 2015 at 09:37

+++ b/core/modules/forum/src/ForumManager.php
@@ -282,7 +286,7 @@ public function getTopics($tid, AccountInterface $account) {
-  protected function getTopicOrder($sortby) {
+  private function getTopicOrder($sortby) {

@@ -311,7 +315,7 @@ protected function getTopicOrder($sortby) {
-  protected function lastVisit($nid, AccountInterface $account) {
+  private function lastVisit($nid, AccountInterface $account) {

@@ -333,7 +337,7 @@ protected function lastVisit($nid, AccountInterface $account) {
-  protected function getLastPost($tid) {
+  private function getLastPost($tid) {

@@ -374,7 +378,7 @@ protected function getLastPost($tid) {
-  protected function getForumStatistics($tid) {
+  private function getForumStatistics($tid) {

And those are exactly things that I frequently see overriding in "custom" space.

E.g. I want to define additional topic orders or change the topic order to depend on something else, too ...

forumStatistics or lastVisit might be a slow query on my site, can't I exchange it?

I might have a better algorithm to get last post data, why is overridding not possible, etc.

Comment #4

larowlan

🇦🇺🏝.au GMT+10

CreditAttribution: larowlan as a volunteer commented 25 May 2015 at 21:27

File	Size
forum-api.2.patch	21.05 KB

Removes the contentious private

Comment #5

Crell CreditAttribution: Crell as a volunteer commented 26 May 2015 at 04:16

```
+++ b/core/modules/forum/forum.install
@@ -59,6 +63,8 @@ function forum_uninstall() {
 /**
  * Implements hook_schema().
+ *
+ * @internal
  */
 function forum_schema() {
```
As webchick noted in the parent issue, we should probably just document that hook implementations are always @internal unless specified otherwise and save ourselves a ton of typing.

+++ b/core/modules/forum/src/Controller/ForumController.php
index b50f29b..eb0c25f 100644
--- a/core/modules/forum/src/ForumIndexStorage.php

--- a/core/modules/forum/src/ForumIndexStorage.php
+++ b/core/modules/forum/src/ForumIndexStorage.php

+++ b/core/modules/forum/src/ForumIndexStorage.php
+++ b/core/modules/forum/src/ForumIndexStorage.php
@@ -27,6 +27,8 @@ class ForumIndexStorage implements ForumIndexStorageInterface {

@@ -27,6 +27,8 @@ class ForumIndexStorage implements ForumIndexStorageInterface {
    *
    * @param \Drupal\Core\Database\Connection $database
    *   The current database connection.
+   *
+   * @internal
    */
   function __construct(Connection $database) {
     $this->database = $database;
@@ -34,6 +36,8 @@ function __construct(Connection $database) {

@@ -34,6 +36,8 @@ function __construct(Connection $database) {
 
   /**
    * {@inheritdoc}
+   *
+   * @api
    */
   public function getOriginalTermId(NodeInterface $node) {
     return $this->database->queryRange("SELECT f.tid FROM {forum} f INNER JOIN {node} n ON f.vid = n.vid WHERE n.nid = :nid ORDER BY f.vid DESC", 0, 1, array(':nid' => $node->id()))->fetchField();
@@ -41,6 +45,8 @@ public function getOriginalTermId(NodeInterface $node) {

If the non-constructor public methods are all @api, just make the class @api and skip the extra typing. (Same for @internal.) Assume that public methods inherit the @api/@internal status of their class.

Comment #6

26 May 2015 at 04:16

Version:

8.0.x-dev

» 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Comment #7

26 May 2015 at 04:16

Version:

8.1.x-dev

» 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Comment #8

26 May 2015 at 04:16

Version:

8.2.x-dev

» 8.3.x-dev

Drupal 8.2.6 was released on February 1, 2017 and is the final full bugfix release for the Drupal 8.2.x series. Drupal 8.2.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.3.0 on April 5, 2017. (Drupal 8.3.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.3.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Comment #9

26 May 2015 at 04:16

Version:

8.3.x-dev

» 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Comment #10

26 May 2015 at 04:16

Version:

8.4.x-dev

» 8.5.x-dev

Drupal 8.4.4 was released on January 3, 2018 and is the final full bugfix release for the Drupal 8.4.x series. Drupal 8.4.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.5.0 on March 7, 2018. (Drupal 8.5.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.5.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Comment #11

26 May 2015 at 04:16

Version:

8.5.x-dev

» 8.6.x-dev

Drupal 8.5.6 was released on August 1, 2018 and is the final bugfix release for the Drupal 8.5.x series. Drupal 8.5.x will not receive any further development aside from security fixes. Sites should prepare to update to 8.6.0 on September 5, 2018. (Drupal 8.6.0-rc1 is available for testing.)

Bug reports should be targeted against the 8.6.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Comment #12

26 May 2015 at 04:16

Version:

8.6.x-dev

» 8.8.x-dev

Drupal 8.6.x will not receive any further development aside from security fixes. Bug reports should be targeted against the 8.8.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.9.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Comment #13

26 May 2015 at 04:16

Version:

8.8.x-dev

» 8.9.x-dev

Drupal 8.8.7 was released on June 3, 2020 and is the final full bugfix release for the Drupal 8.8.x series. Drupal 8.8.x will not receive any further development aside from security fixes. Sites should prepare to update to Drupal 8.9.0 or Drupal 9.0.0 for ongoing support.

Bug reports should be targeted against the 8.9.x-dev branch from now on, and new development or disruptive changes should be targeted against the 9.1.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

Comment #14

26 May 2015 at 04:16

Version:

8.9.x-dev

» 9.2.x-dev

Drupal 8 is end-of-life as of November 17, 2021. There will not be further changes made to Drupal 8. Bugfixes are now made to the 9.3.x and higher branches only. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Comment #15

26 May 2015 at 04:16

Version:

9.2.x-dev

» 9.3.x-dev

Comment #16

26 May 2015 at 04:16

Version:

9.3.x-dev

» 9.4.x-dev

Drupal 9.3.15 was released on June 1st, 2022 and is the final full bugfix release for the Drupal 9.3.x series. Drupal 9.3.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.4.x-dev branch from now on, and new development or disruptive changes should be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Comment #17

smustgrave CreditAttribution: smustgrave at Mobomo commented 23 November 2022 at 20:25

Status:

Needs review

» Postponed (maintainer needs more info)

Looks like changes were requested in #5.

This has been 8 years so wonder if this is still a valid task? If so please move back to Needs Work.

Comment #18

23 November 2022 at 20:25

Version:

9.4.x-dev

» 9.5.x-dev

Drupal 9.4.9 was released on December 7, 2022 and is the final full bugfix release for the Drupal 9.4.x series. Drupal 9.4.x will not receive any further development aside from security fixes. Drupal 9 bug reports should be targeted for the 9.5.x-dev branch from now on, and new development or disruptive changes should be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Comment #19

quietone CreditAttribution: quietone at PreviousNext commented 7 February 2023 at 10:09

Status:

Postponed (maintainer needs more info)

» Postponed

Forum is approved for removal. See #1898812: [policy] Deprecate forum module for removal in Drupal 11

This is now Postponed. The status is set according to two policies. The Remove a core extension and move it to a contributed project and the Extensions approved for removal policies.

It will be moved to the contributed extension once the Drupal 11 branch is open.

Comment #20

7 February 2023 at 10:09

Version:

9.5.x-dev

» 11.x-dev

Drupal core is moving towards using a “main” branch. As an interim step, a new 11.x branch has been opened, as Drupal.org infrastructure cannot currently fully support a branch named main. New developments and disruptive changes should now be targeted for the 11.x branch. For more information, see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.