Posted by xjm

Problem/Motivation

There are several deficiencies in Views' API documentation:

  • While views.api.php has been updated to Drupal 8, basic explanations for handler plugin types are missing.
  • The hook examples need review by an experienced Drupal 8 Views developer; many were updated but some may still be out of date.
  • Much of the documentation has not been updated from Drupal 7 (or, in some cases, Drupal 6)...
  • All base plugins and handlers need significantly more documentation.
  • Plugin @defgroup/@ingroup were moved around when Views' classes were converted to PSR-0, and as a result some classes are probably missing their @ingroup, while Views also has the odd pattern at present of having an @defgroup wrapped around a single PSR-0 class in the base class for a kind of plugin.
  • Critical documentation like function and method summaries, parameter documentation, and typehints is widely missing.
  • In general, many parts of Views do not conform to Drupal 8 documentation style guidelines.

Proposed resolution

  1. Throughout the release cycle, new patches added to Views will be adjusted to core documentation standards defined in the Core documentation gate minimum requirements.
  2. We will hold a virtual sprint to do general cleanup of the Views API documentation. This sprint will not begin until at least Feburary 2013. There are two important reasons for postponing the sprint until then:
    • Documentation cleanup patches often take longer to review than to create, and while they are great contribution opportunities for novices, they also need to be reviewed for their accuracy by an experienced developer. The VDC team needs to focus important features and APIs at this point in the release cycle.
    • Documentation cleanups frequently conflict with other patches, because they affect many lines scattered throughout the codebase, in and around actively developed APIs. With a record volume of patches currently being submitted each month, early feature freeze is the worst possible time to force rerolls. (See the graph below, from Dries' blog.)
      drupal-8-core-monthly-patch-volume.jpeg

Remaining tasks

Related issues

CommentFileSizeAuthor
drupal-8-core-monthly-patch-volume.jpeg108.88 KBxjm

Comments

xjm’s picture

xjm
she/her
Primary language English
commented
Issue summary: View changes

Updated issue summary.

hansfn’s picture

hansfn commented

Yes, improved Views documentation would really help. I'm trying (for fun) to port Views Send, a Views Form implementation, to Drupal 8. It started with hook_views_api being gone and the views.inc file (in a subdirectory) not being loaded ... Do you plan to document such changes on http://drupal.org/list-changes/drupal or to create a separate page for Views?

dawehner’s picture

dawehner
Primary language German
commented

@hansfn
Yeah this changed quite a lot, so I documented the hook_views_api() change in http://drupal.org/node/1875596

xjm’s picture

xjm
she/her
Primary language English
commented

@hansfn, see http://drupal.org/list-changes/views. We've started adding the change notifications from 7.x-3.x to 8.x core views there.

hansfn’s picture

hansfn commented

Thx, dawehner and xjm, for the quick reply.

Regarding the list of changes in Views, I can't find a general note about how to extended Views classes - for example views_handler_field. (I guess I can look at for example the core user module to get the idea - I already have and I think I have gotten it.)

PS! It seems some of my problem with the lack of documentation was related to the change list. I thought http://drupal.org/list-changes would list everything, but it's only listening core changes (as the title actually says). I'm not sure how I was supposed to find http://drupal.org/list-changes/views ...

xjm’s picture

xjm
she/her
Primary language English
commented

Well, the Views change list is also incomplete (we identified a bunch of changes we need to add change notices for at our last sprint). We're planning to really focus on the documentation later in the release cycle. The link to the Views change notices is in the far lower right of the Views project page.

dawehner’s picture

dawehner
Primary language German
commented

The guide how to write plugins in d8 is probably a helpful start for many general questions: http://drupal.org/node/1637614

hansfn’s picture

hansfn commented

Thx again, dawehner and xjm. Looking forward to a D8 version of Views Send ...

hansfn’s picture

hansfn commented

OK, I just tried to add a change notice - get_url has been replaced with getURL - but I wasn't able to select the correct project. Entering "Views" in the project box on http://drupal.org/node/add/changenotice didn't give me a suggestion I could use. Any hints?

PS! Maybe I should make noise somewhere else? I feel I'm abusing this issue now.

dawehner’s picture

dawehner
Primary language German
commented

@hansfn
Most functions will be replaced to be camelCase so we maybe need just a big big table.
Regarding entering views, just type it in, it works, even the autocompletion fails.

dawehner’s picture

dawehner
Primary language German
commented
Issue summary: View changes

Updated issue summary.

xjm’s picture

xjm
she/her
Primary language English
commented

I added #1882558: [META] Document all views plugins types to the summary. If folks are interested in helping with documentation, that's a place to help out now!

leehunter’s picture

leehunter commented

User-facing documentation (i.e. the old advanced help content) issue is here: http://drupal.org/node/1892470

leehunter’s picture

leehunter commented
Issue summary: View changes

Updated issue summary.

xjm’s picture

xjm
she/her
Primary language English
commented
Issue summary: View changes

Updated issue summary.

xjm’s picture

xjm
she/her
Primary language English
commented
Issue summary: View changes

Removing myself from the author field so that I can unfollow the issue. --xjm

jmarkel’s picture

jmarkel commented
Issue tags: -Novice

I am removing the Novice tag from this issue because neither of the two remaining tasks are Novice tasks.

I’m using this documentation as a source: https://www.drupal.org/core-mentoring/novice-tasks#avoid

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.

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.

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.

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.

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.

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.

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.

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.

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.

Version: 9.2.x-dev » 9.3.x-dev

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.

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.

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.

quietone’s picture

quietone commented
Status: Postponed » Fixed

Came across this issue today. I don't see what this is postponed on so normally I would set an issue to 'Active'. However, all the remaining tasks here have been completed, so closing as fixed makes more sense. That is not to say that Views documentation can't be improved, just that this issue is complete. There are existing issues for views to improve documentation as well. Therefor, closing this meta.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.