JS docs initiative: Add inline-docs for JavaScript! (part 2)

Because of a restriction of wordpress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/, you cannot comment on posts older than 120 days. This new post can be used to track the work on JavascriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. inline-docs. The original post on the JS docs initiative can be found here. In this post I have excluded files that have already been completed.

At the bottom is a list of every first-party JavaScript file in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. Files with a checkmark have been patched and are considered completed. Files marked with (username #xxxxx) are already claimed, and being worked on.

Directly below is the process we’re using to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.

How to contribute

  1. Familiarize yourself with the JavaScript documentation standard, as well as the formatting guidelines and documenting tips.
  2. Check the list first to make sure the file you want to work on hasn’t already been claimed.
  3. Update your local WordPress SVN (use svn up) or Git repo (use git pull) to the latest version of WordPress trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision..
  4. Create a new ticket on Trac for the file.
    • Format the title as “JSDoc: path/to/file.js”.
    • The Type should be “defect (bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.)”.
    • Assign the ticketticket Created for both bug reports and feature development on the bug tracker. to the component the file is associated with.
    • Leave the Version blank.
    • Add the docs and javascript focuses.
  5. Edit the file, and make a patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing.. Please make sure you create the patch from the root directory of your WordPress SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase. or GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/. checkout.
  6. Upload your patch to the TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket you created, and add the keyword “has-patch”.

We’d like to welcome everyone to start contributing inline documentation! You can start contributing by picking a file from the list of unclaimed files below and claiming it in the comments. Please also see the JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. docs handbook page for a step by step guide on how to get started.

Note: Note: To give everyone a chance to claim a file and to ensure the work proceeds as quickly as possible, please only work on one file at a time.

Determining the since version

We use JSDoc’s @since tag to indicate when a particular function was added to WordPress core. When you are documenting a function, you will also need to identify when that function was first introduced.

The recommended tool to use when searching for the version something was added to WordPress is svn blame. An additional resource for hooks is the WordPress Hooks Database. If, after using these tools, the version number cannot be determined, use @since Unknown.

If you use the git repository of WordPress you can also use git to determine the @since version. Either use git blame or the GitHub blame function. Once you have the commit hash which introduced a piece of code you can find out the version by using git tag --contains [commit-hash]. This will list all versions a certain commit has been shipped in. The lowest version is then what you put after the @since annotation.

Note: Make sure that the commit you found it the actual commit where a piece of code was introduced. JavaScript files have been moved around a lot in the past, so make sure to take that into account.

Note: All @since tags should follow the three digit x.x.x format.

Keeping Discussions Focused:

Any discussion about the specifics of a patch itself should happen on Trac. Any discussion about the broader scope of what we’re trying to do should take place during the weekly devchat. That’s either #core-js or #core.

Files needing patches:

Checked files are completed, marked files are claimed

  • src/js/_enqueues/wp/customize/controls.js (@jjcomack)
  • src/js/_enqueues/wp/customize/nav-menus.js
  • src/js/_enqueues/wp/customize/widgets.js
  • src/js/_enqueues/lib/gallery.js (@hunkriyaz)
  • src/js/_enqueues/admin/link.js (@andg)
  • src/js/_enqueues/lib/nav-menu.js
  • src/js/_enqueues/admin/plugin-install.js
  • src/js/_enqueues/wp/revisions.js
  • src/js/_enqueues/admin/set-post-thumbnail.js
  • src/js/_enqueues/wp/svg-painter.js
  • src/js/_enqueues/wp/theme.js (@igorsch)
  • src/js/_enqueues/wp/updates.js
  • src/js/_enqueues/admin/user-profile.js
  • src/js/_enqueues/admin/widgets.js
  • src/js/_enqueues/deprecated/fullscreen-stub.js
  • src/js/_enqueues/wp/customize/base.js
  • src/js/_enqueues/wp/customize/loader.js
  • src/js/_enqueues/wp/customize/models.js
  • src/js/_enqueues/wp/customize/preview-nav-menus.js
  • src/js/_enqueues/wp/customize/preview.js
  • src/js/_enqueues/wp/customize/selective-refresh.js
  • src/js/_enqueues/wp/customize/views.js
  • src/js/_enqueues/wp/mce-view.js
  • src/js/_enqueues/wp/media/audiovideo.js
  • src/js/_enqueues/wp/media/editor.js
  • src/js/_enqueues/wp/media/grid.js
  • src/js/_enqueues/wp/media/models.js
  • src/js/_enqueues/wp/media/views.js
  • src/js/media/controllers/audio-details.js
  • src/js/media/controllers/collection-add.js
  • src/js/media/controllers/collection-edit.js
  • src/js/media/controllers/edit-attachment-metadata.js
  • src/js/media/controllers/embed.js
  • src/js/media/controllers/featured-image.js
  • src/js/media/controllers/image-details.js
  • src/js/media/controllers/library.js
  • src/js/media/controllers/media-library.js
  • src/js/media/controllers/region.js
  • src/js/media/controllers/replace-image.js
  • src/js/media/controllers/site-icon-cropper.js
  • src/js/media/controllers/state-machine.js
  • src/js/media/controllers/state.js
  • src/js/media/controllers/video-details.js
  • src/js/media/models/attachment.js
  • src/js/media/models/post-image.js
  • src/js/media/models/post-media.js
  • src/js/media/models/query.js
  • src/js/media/models/selection.js
  • src/js/media/routers/manage.js
  • src/js/media/utils/selection-sync.js
  • src/js/media/views/attachment-compat.js
  • src/js/media/views/attachment-filters.js
  • src/js/media/views/attachment-filters/all.js
  • src/js/media/views/attachment-filters/date.js
  • src/js/media/views/attachment-filters/uploaded.js
  • src/js/media/views/attachment.js (@digitalarticle)
  • src/js/media/views/attachment/details-two-column.js
  • src/js/media/views/attachment/details.js (@maartenleenders)
  • src/js/media/views/attachment/edit-library.js
  • src/js/media/views/attachment/edit-selection.js
  • src/js/media/views/attachment/library.js
  • src/js/media/views/attachment/selection.js
  • src/js/media/views/attachments/browser.js
  • src/js/media/views/attachments/selection.js
  • src/js/media/views/audio-details.js
  • src/js/media/views/button-group.js
  • src/js/media/views/button.js (@dfangstrom)
  • src/js/media/views/button/delete-selected-permanently.js
  • src/js/media/views/button/delete-selected.js
  • src/js/media/views/button/select-mode-toggle.js
  • src/js/media/views/cropper.js
  • src/js/media/views/edit-image-details.js
  • src/js/media/views/edit-image.js
  • src/js/media/views/embed.js
  • src/js/media/views/embed/image.js
  • src/js/media/views/embed/link.js
  • src/js/media/views/embed/url.js
  • src/js/media/views/focus-manager.js
  • src/js/media/views/frame.js
  • src/js/media/views/frame/audio-details.js
  • src/js/media/views/frame/edit-attachments.js
  • src/js/media/views/frame/image-details.js
  • src/js/media/views/frame/manage.js
  • src/js/media/views/frame/media-details.js
  • src/js/media/views/frame/post.js
  • src/js/media/views/frame/select.js
  • src/js/media/views/frame/video-details.js
  • src/js/media/views/iframe.js
  • src/js/media/views/image-details.js
  • src/js/media/views/label.js
  • src/js/media/views/media-details.js
  • src/js/media/views/media-frame.js
  • src/js/media/views/menu-item.js
  • src/js/media/views/menu.js
  • src/js/media/views/modal.js
  • src/js/media/views/priority-list.js
  • src/js/media/views/router-item.js
  • src/js/media/views/router.js
  • src/js/media/views/search.js (@boblinthorst)
  • src/js/media/views/selection.js
  • src/js/media/views/settings.js
  • src/js/media/views/settings/attachment-display.js
  • src/js/media/views/settings/gallery.js
  • src/js/media/views/settings/playlist.js
  • src/js/media/views/sidebar.js
  • src/js/media/views/site-icon-cropper.js
  • src/js/media/views/site-icon-preview.js
  • src/js/media/views/toolbar.js
  • src/js/media/views/toolbar/embed.js
  • src/js/media/views/toolbar/select.js
  • src/js/media/views/uploader/editor.js
  • src/js/media/views/uploader/inline.js
  • src/js/media/views/uploader/status-error.js
  • src/js/media/views/uploader/status.js
  • src/js/media/views/uploader/window.js
  • src/js/media/views/video-details.js
  • src/js/media/views/view.js
  • src/js/_enqueues/lib/quicktags.js
  • src/js/_enqueues/wp/shortcode.js (@hanopcan)
  • src/js/_enqueues/lib/cookies.js
  • src/js/_enqueues/wp/a11y.js
  • src/js/_enqueues/lib/ajax-response.js
  • src/js/_enqueues/wp/api.js
  • src/js/_enqueues/lib/auth-check.js (@pskli)
  • src/js/_enqueues/wp/custom-header.js (@man4toman)
  • src/js/_enqueues/lib/embed-template.js
  • src/js/_enqueues/wp/embed.js
  • src/js/_enqueues/wp/emoji.js (@igorsch, @nicollle)
  • src/js/_enqueues/lib/list-revisions.js
  • src/js/_enqueues/lib/lists.js
  • src/js/_enqueues/lib/pointer.js (@maartenleenders)
  • src/js/_enqueues/wp/util.js
  • src/js/_enqueues/lib/link.js

Current status:

Happy documenting!

#inline-docs

#javascript

JS docs initiative: Add inline-docs for JavaScript!

There is a new post which you can comment on to claim files.

We are pleased to announce the JS docs initiative! It’s an ongoing effort to get all JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. files in WordPress well-documented and make this documentation easily accessible. JavaScript development within WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. is speeding up fast, and better documentation will help this work progress as smoothly as possible.

In the last few months, we’ve fixed the JavaScript documentation standards by discussing sticking points in the #core-js weekly meeting. The structural documentation of all the Backbone classes has also been fixed (major props to @herregroen for fixing this).

At the bottom is a list of every first-party JavaScript file in core. Files with a checkmark have been patched and are considered completed. Files marked with (username #xxxxx) are already claimed, and being worked on.

Directly below is the process we’re using to make sure each of these files can get patched swiftly with no duplicated nor wasted efforts.

How to contribute

  1. Familiarize yourself with the JavaScript documentation standard, as well as the formatting guidelines and documenting tips.
  2. Check the list first to make sure the file you want to work on hasn’t already been claimed.
  3. Update your local WordPress SVN (use svn up) or Git repo (use git pull) to the latest version of WordPress trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision..
  4. Create a new ticket on Trac for the file.
    • Format the title as “JSDoc: path/to/file.js”.
    • The Type should be “defect (bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority.)”.
    • Assign the ticketticket Created for both bug reports and feature development on the bug tracker. to the component the file is associated with.
    • Leave the Version blank.
    • Add the docs and javascript focuses.
  5. Edit the file, and make a patchpatch A special text file that describes changes to code, by identifying the files and lines which are added, removed, and altered. It may also be referred to as a diff. A patch can be applied to a codebase for testing.. Please make sure you create the patch from the root directory of your WordPress SVNSVN Subversion, the popular version control system (VCS) by the Apache project, used by WordPress to manage changes to its codebase. or GitGit Git is a free and open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency. Git is easy to learn and has a tiny footprint with lightning fast performance. Most modern plugin and theme development is being done with this version control system. https://git-scm.com/. checkout.
  6. Upload your patch to the TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. ticket you created, and add the keyword “has-patch”.

We’d like to welcome everyone to start contributing inline documentation! You can start contributing by picking a file from the list of unclaimed files below and claiming it in the comments. Please also see the JSJS JavaScript, a web scripting language typically executed in the browser. Often used for advanced user interfaces and behaviors. docs handbook page for a step by step guide on how to get started.

Note: Note: To give everyone a chance to claim a file and to ensure the work proceeds as quickly as possible, please only work on one file at a time.

Determining the since version

We use JSDoc’s @since tag to indicate when a particular function was added to WordPress core. When you are documenting a function, you will also need to identify when that function was first introduced.

The recommended tool to use when searching for the version something was added to WordPress is svn blame. An additional resource for hooks is the WordPress Hooks Database. If, after using these tools, the version number cannot be determined, use @since Unknown.

If you use the git repository of WordPress you can also use git to determine the @since version. Either use git blame or the GitHub blame function. Once you have the commit hash which introduced a piece of code you can find out the version by using git tag --contains [commit-hash]. This will list all versions a certain commit has been shipped in. The lowest version is then what you put after the @since annotation.

Note: Make sure that the commit you found it the actual commit where a piece of code was introduced. JavaScript files have been moved around a lot in the past, so make sure to take that into account.

Note: All @since tags should follow the three digit x.x.x format.

Keeping Discussions Focused:

Any discussion about the specifics of a patch itself should happen on Trac. Any discussion about the broader scope of what we’re trying to do should take place during the weekly devchat. That’s either #core-js or #core.

Files needing patches:

Checked files are completed, marked files are claimed

  • wp-admin/js/accordion.js
  • wp-admin/js/bookmarklet.js
  • wp-admin/js/color-picker.js
  • wp-admin/js/comment.js
  • wp-admin/js/common.js
  • wp-admin/js/custom-background.js
  • wp-admin/js/custom-header.js
  • wp-admin/js/customize-controls.js (@jjcomack)
  • wp-admin/js/customize-nav-menus.js
  • wp-admin/js/customize-widgets.js
  • wp-admin/js/edit-comments.js (@atimmer)
  • wp-admin/js/editor-expand.js
  • wp-admin/js/editor.js
  • wp-admin/js/gallery.js (@hunkriyaz)
  • wp-admin/js/image-edit.js
  • wp-admin/js/inline-edit-post.js
  • wp-admin/js/inline-edit-tax.js
  • wp-admin/js/language-chooser.js
  • wp-admin/js/link.js
  • wp-admin/js/media-gallery.js
  • wp-admin/js/media-upload.js
  • wp-admin/js/media.js
  • wp-admin/js/nav-menu.js
  • wp-admin/js/password-strength-meter.js
  • wp-admin/js/plugin-install.js
  • wp-admin/js/post.js
  • wp-admin/js/postbox.js
  • wp-admin/js/press-this.js
  • wp-admin/js/revisions.js
  • wp-admin/js/set-post-thumbnail.js
  • wp-admin/js/svg-painter.js
  • wp-admin/js/tags-box.js (@carolinegeven)
  • wp-admin/js/tags.js
  • wp-admin/js/theme.js
  • wp-admin/js/updates.js
  • wp-admin/js/user-profile.js
  • wp-admin/js/user-suggest.js (@timhavinga)
  • wp-admin/js/widgets.js
  • wp-admin/js/word-count.js
  • wp-admin/js/wp-fullscreen-stub.js
  • wp-admin/js/xfn.js (@kapteinbluf)
  • wp-includes/js/admin-bar.js
  • wp-includes/js/autosave.js
  • wp-includes/js/comment-reply.js
  • wp-includes/js/customize-base.js
  • wp-includes/js/customize-loader.js
  • wp-includes/js/customize-models.js
  • wp-includes/js/customize-preview-nav-menus.js
  • wp-includes/js/customize-preview-widgets.js
  • wp-includes/js/customize-preview.js
  • wp-includes/js/customize-selective-refresh.js
  • wp-includes/js/customize-views.js
  • wp-includes/js/dashboard.js
  • wp-includes/js/heartbeat.js
  • wp-includes/js/mce-view.js
  • wp-includes/js/media-audiovideo.js
  • wp-includes/js/media-editor.js
  • wp-includes/js/media-grid.js
  • wp-includes/js/media-models.js
  • wp-includes/js/media-views.js
  • wp-includes/js/media/audiovideo.manifest.js
  • wp-includes/js/media/controllers/audio-details.js
  • wp-includes/js/media/controllers/collection-add.js
  • wp-includes/js/media/controllers/collection-edit.js
  • wp-includes/js/media/controllers/cropper.js
  • wp-includes/js/media/controllers/customize-image-cropper.js
  • wp-includes/js/media/controllers/edit-attachment-metadata.js
  • wp-includes/js/media/controllers/edit-image.js
  • wp-includes/js/media/controllers/embed.js
  • wp-includes/js/media/controllers/featured-image.js
  • wp-includes/js/media/controllers/gallery-add.js (@atimmer)
  • wp-includes/js/media/controllers/gallery-edit.js (@manuelaugustin)
  • wp-includes/js/media/controllers/image-details.js
  • wp-includes/js/media/controllers/library.js
  • wp-includes/js/media/controllers/media-library.js
  • wp-includes/js/media/controllers/region.js
  • wp-includes/js/media/controllers/replace-image.js
  • wp-includes/js/media/controllers/site-icon-cropper.js
  • wp-includes/js/media/controllers/state-machine.js
  • wp-includes/js/media/controllers/state.js
  • wp-includes/js/media/controllers/video-details.js
  • wp-includes/js/media/grid.manifest.js
  • wp-includes/js/media/models.manifest.js
  • wp-includes/js/media/models/attachment.js
  • wp-includes/js/media/models/post-image.js
  • wp-includes/js/media/models/post-media.js
  • wp-includes/js/media/models/query.js
  • wp-includes/js/media/models/selection.js
  • wp-includes/js/media/routers/manage.js
  • wp-includes/js/media/utils/selection-sync.js
  • wp-includes/js/media/views.manifest.js
  • wp-includes/js/media/views/attachment-compat.js
  • wp-includes/js/media/views/attachment-filters.js
  • wp-includes/js/media/views/attachment-filters/all.js
  • wp-includes/js/media/views/attachment-filters/date.js
  • wp-includes/js/media/views/attachment-filters/uploaded.js
  • wp-includes/js/media/views/attachment.js
  • wp-includes/js/media/views/attachment/details-two-column.js
  • wp-includes/js/media/views/attachment/details.js (@maartenleenders)
  • wp-includes/js/media/views/attachment/edit-library.js
  • wp-includes/js/media/views/attachment/edit-selection.js
  • wp-includes/js/media/views/attachment/library.js
  • wp-includes/js/media/views/attachment/selection.js
  • wp-includes/js/media/views/attachments.js
  • wp-includes/js/media/views/attachments/browser.js
  • wp-includes/js/media/views/attachments/selection.js
  • wp-includes/js/media/views/audio-details.js
  • wp-includes/js/media/views/button-group.js
  • wp-includes/js/media/views/button.js
  • wp-includes/js/media/views/button/delete-selected-permanently.js
  • wp-includes/js/media/views/button/delete-selected.js
  • wp-includes/js/media/views/button/select-mode-toggle.js
  • wp-includes/js/media/views/cropper.js (@kapteinbluf)
  • wp-includes/js/media/views/edit-image-details.js
  • wp-includes/js/media/views/edit-image.js
  • wp-includes/js/media/views/embed.js
  • wp-includes/js/media/views/embed/image.js
  • wp-includes/js/media/views/embed/link.js
  • wp-includes/js/media/views/embed/url.js
  • wp-includes/js/media/views/focus-manager.js
  • wp-includes/js/media/views/frame.js
  • wp-includes/js/media/views/frame/audio-details.js
  • wp-includes/js/media/views/frame/edit-attachments.js
  • wp-includes/js/media/views/frame/image-details.js
  • wp-includes/js/media/views/frame/manage.js
  • wp-includes/js/media/views/frame/media-details.js
  • wp-includes/js/media/views/frame/post.js
  • wp-includes/js/media/views/frame/select.js
  • wp-includes/js/media/views/frame/video-details.js
  • wp-includes/js/media/views/iframe.js
  • wp-includes/js/media/views/image-details.js
  • wp-includes/js/media/views/label.js
  • wp-includes/js/media/views/media-details.js
  • wp-includes/js/media/views/media-frame.js
  • wp-includes/js/media/views/menu-item.js
  • wp-includes/js/media/views/menu.js
  • wp-includes/js/media/views/modal.js
  • wp-includes/js/media/views/priority-list.js
  • wp-includes/js/media/views/router-item.js
  • wp-includes/js/media/views/router.js
  • wp-includes/js/media/views/search.js
  • wp-includes/js/media/views/selection.js
  • wp-includes/js/media/views/settings.js
  • wp-includes/js/media/views/settings/attachment-display.js
  • wp-includes/js/media/views/settings/gallery.js
  • wp-includes/js/media/views/settings/playlist.js
  • wp-includes/js/media/views/sidebar.js
  • wp-includes/js/media/views/site-icon-cropper.js
  • wp-includes/js/media/views/site-icon-preview.js
  • wp-includes/js/media/views/spinner.js (@avillegasn)
  • wp-includes/js/media/views/toolbar.js
  • wp-includes/js/media/views/toolbar/embed.js
  • wp-includes/js/media/views/toolbar/select.js
  • wp-includes/js/media/views/uploader/editor.js
  • wp-includes/js/media/views/uploader/inline.js
  • wp-includes/js/media/views/uploader/status-error.js
  • wp-includes/js/media/views/uploader/status.js
  • wp-includes/js/media/views/uploader/window.js
  • wp-includes/js/media/views/video-details.js
  • wp-includes/js/media/views/view.js
  • wp-includes/js/quicktags.js
  • wp-includes/js/shortcode.js
  • wp-includes/js/tw-sack.js
  • wp-includes/js/utils.js
  • wp-includes/js/wp-a11y.js
  • wp-includes/js/wp-ajax-response.js
  • wp-includes/js/wp-api.js
  • wp-includes/js/wp-auth-check.js
  • wp-includes/js/wp-backbone.js
  • wp-includes/js/wp-custom-header.js
  • wp-includes/js/wp-embed-template.js
  • wp-includes/js/wp-embed.js
  • wp-includes/js/wp-emoji-loader.js (@dfangstrom)
  • wp-includes/js/wp-emoji.js (@igorsch, @nicollle)
  • wp-includes/js/wp-list-revisions.js
  • wp-includes/js/wp-lists.js
  • wp-includes/js/wp-pointer.js (@maartenleenders)
  • wp-includes/js/wp-util.js
  • wp-includes/js/wpdialog.js (@lisannekluitmans)
  • wp-includes/js/wplink.js
  • wp-includes/js/zxcvbn-async.js (@lisannekluitmans)

Current status:

Happy documenting!

#inline-docs

#javascript

Continuing inline docs improvements adjacent to 4.8

As we’re now into the full throes of the 4.8 cycle, the uncertainty that comes with not releasing “until it’s ready” inevitably creates a lull in areas other than the three focuses. Areas like maintaining our inline documentation, which populates the official Code Reference.

In the past, the freshness of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’s inline documentation relied almost entirely on a regular, major releasemajor release A release, identified by the first two numbers (3.6), which is the focus of a full release cycle and feature development. WordPress uses decimaling count for major release versions, so 2.8, 2.9, 3.0, and 3.1 are sequential and comparable in scope. schedule. And due to a preference for keeping the number of changed files low, inclusion of docs fixes in minor releases has previously been a rare occurrence.

Until now.

I’ve spoken with @matt, and the decision has been made to go ahead and prioritize some inline docsinline docs (phpdoc, docblock, xref) fixes for inclusion in minor releases going forward.

As with any decision, there are certainly pros and cons. Here are some of them:

Pros:

  • Ability to continue our ongoing inline docs maintenance adjacent to the 4.8 major release
  • Ability to address some glaring docs errors that we’ve been fixing manually in the Code Reference
  • Continue forward progress in documenting core JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/.
  • Prioritize docs improvements for existing functionality in the three focus areas ahead of the 4.8 release, freeing up resources for documenting new functionality

Cons:

  • Number of changes and changed files in minor releases will increase (within reason)
  • All changes pushed to trunktrunk A directory in Subversion containing the latest development code in preparation for the next major release cycle. If you are running "trunk", then you are on the latest revision. will also need to be backported to the 4.7 (or current stable) branchbranch A directory in Subversion. WordPress uses branches to store the latest development code for each major release (3.9, 4.0, etc.). Branches are then updated with code for any minor releases of that branch. Sometimes, a major version of WordPress and its minor versions are collectively referred to as a "branch", such as "the 4.0 branch".

It’s worth noting that the reason the number of changed files has traditionally been kept low is to reduce the number of automatic update failures. The hope is that since we’ve been pushing automatic updates for 10 major versions now, reliability is less of a factor now than it has been previously.

It’s also worth noting that we shouldn’t expect a downtick in activity for core team resources focused on the three areas following this decision. As always, inline docs contributors will be focused on major release priorities before minor releaseMinor Release A set of releases or versions having the same minor version number may be collectively referred to as .x , for example version 5.2.x to refer to versions 5.2, 5.2.1, 5.2.3, and all other versions in the 5.2 (five dot two) branch of that software. Minor Releases often make improvements to existing features and functionality. ones.

This decision simply maintains the inline docs team’s ability to ensure the usefulness of core’s source documentation for the thousands of users and developers who rely on it every day.

#inline-docs, #minor-releases, #release-process

Docs-focused Bug Scrub Friday

We’ll have a docs-focused bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. scrub Friday, Oct. 7 2016 14:00 CDT in the #docs SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channel, for anyone interested in contributing. We’ll focus on the `needs-docs` keyword first, then on the `docs` focus if there’s time.

#4-7, #bug-scrub, #inline-docs

Docs Bug Scrub this Weekend

Join @morganestes in the #docs channel in SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. on Sunday, Oct. 2, 2016 3:30 p.m. CDT for a docs-focused bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. scrub. We’ll plan for an hour of gardening fun. See you there!

#4-7, #bug-scrub, #inline-docs

We're discussing JS docs at this week's Inline Docs chat

For anyone interested, I’ll be hosting an Inline Docs chat this week, Wednesday 19:00 UTC in #wordpress-sfd on Freenode.

Top of the agenda is discussing options for adopting a documentation standard for coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/.. Anybody is welcome to attend, though we’re particularly interested in input from folks familiar with WordPress core JavaScript.

#inline-docs

Inline Docs Weekly Office Hours Time Change

Quick note to let everyone know that the Inline Docsinline docs (phpdoc, docblock, xref) weekly office hours time is changing.

Due to a schedule conflictconflict A conflict occurs when a patch changes code that was modified after the patch was created. These patches are considered stale, and will require a refresh of the changes before it can be applied, or the conflicts will need to be resolved., we’ll be meeting an hour later, starting this week. Same day (Wednesday), now at 20:00 UTC in #wordpress-sfd.

If you’re interested in contributing to Inline Docs, come join us!

#inline-docs

The State of Inline Docs

We haven’t posted an update in several weeks, so thought we’d bring everyone up to speed on the Inline Docsinline docs (phpdoc, docblock, xref) project.

This project started July at WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. San Francisco as a 3.7 release action item. Work continues into the 3.8 release cycle, and we would like to have the hook documentation completed by the time 3.8 is released in December.

PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 Documentation Standards

The PHP Documentation Standard has been amended several times since it was first published in early September. The latest amendments include:

If you are one of our contributors, please make sure you read the standards again to familiarize yourself with the changes.

WordCamp Contributor Days

We would like to thank WordCamp Toronto (10/6), WordCamp Europe (10/7), and WordCamp Sofia (10/27) for including Inline Docs as part of their respective Contributor Days. Approximately 35 files were documented, and several new contributors had their first patches committed to WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. as a result. Woot!

Contributors

So far, 47 people have received props for submitting inline docs patches:

@admiralthrawn, @aeg0125, @a.hoereth, @andg, @aralbald, @bananastalktome, @ben.moody, @betzster, @bftrick, @dllh, @drewapicture, @dougwollison, @dustyf, @enej, @ericlewis, @Faison, @FrankKlein, @gayadesign, @gizburdt, @johnafish, @johnbillion, @jonlynch, @kpdesign, @l10nL10n Localization, or the act of translating code into one's own language. Also see internationalization. Often written with an uppercase L so it is not confused with the capital letter i or the numeral 1. WordPress has a capable and dynamic group of polyglots who take WordPress to more than 70 different locales., @nacin, @naomicbush, @NikV, @ninio, @miyauchi, @morduak, @Nao, @natejacobs, @netweb, @nukaga, @nullvariable, @pauldewouters, @r3df, @rzen, @sboisvert, @SergeyBiryukov, @ShinichiN, @Siobhyb, @swissspidy, @tmtoy, @tomauger, @tw2113, @vinod dalvi

There are 10 other contributors with patches waiting to be reviewed and committed that will be added to this list. We want to thank everyone for their participation so far, and hope you continue contributing!

Progress To Date

According to the “master list“, there are 185 files containing hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. to be documented. The current status, as of today:

  • Completed: 92 files (49.72%)
  • In progress: 23 files
  • Available to claim: 70 files

Weekly Office Hours

We continue to hold weekly office hours meetings on Wednesdays at 19:00 UTC in #wordpress-sfd.

#3-8, #inline-docs

Inline Docs Progress for 3.7

After last week’s weekly Inline Docsinline docs (phpdoc, docblock, xref) meeting we decided to begin doing a weekly ticketticket Created for both bug reports and feature development on the bug tracker. triagetriage The act of evaluating and sorting bug reports, in order to decide priority, severity, and other factors. on Wednesdays.

As of last Wednesday, we’re happy to report that 19 patches have been committed to coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. from 12 different contributors. We’ve also updated the original make/core post to reflect the files that have been completed (please go claim some!). You can see the full report of last week’s triage on TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress.. It’s really spectacular, and you should show some gratitude towards Drew for putting the report together.

Finally, beginning this week, our weekly inline-docs office hours are moving to #wordpress-sfd on Freenode. They’ll continue to be held on Wednesdays at 18:00 UTC, and we hope you can join us!

#3-7, #inline-docs

3.7 Inline Docs Weekly Office Hours

There will be a weekly office hours meeting on Wednesday, September 11, 2013 at 18:00 UTC in #wordpress-dev. Agenda includes status update on the hooks initiative that kicked off last week, and answering questions anyone may have about the effort.

If you’re interested in participating, please plan on attending.

#3-7, #inline-docs