How to resolve a dev-doc-needed bug

Bugzilla is a web-based application that is used to track all changes to all Mozilla software projects. Some bugs (flagged with the "dev-doc-needed" keyword) require changes to the documentation on MDN as well as changes to the source code. However, sometimes the comments and descriptions in bugs are obscure and it is difficult to understand what needs to be done on MDN. This page provides a description and example of the steps we use to update MDN.

A typical JavaScript update

MDN Doc bug tracker

The first step in addressing a bug with the "dev-doc-needed" keyword is to find a bug with the "dev-doc-needed" keyword. The MDN doc bug tracking sheet is a spreadsheet that collects bugs that require updates on MDN, and provides additional comments from the MDN writers.

Bugzilla

Your search in the doc bug tracking sheet might have returned bug #761495. In Bugzilla, we see that bug #761495 has the title: "(harmony:inthelpers) add Number.isInteger/toInteger." This suggests a couple of things:

  • "(harmony:inthelpers)": "Harmony" is a new edition of ECMAScript, the parent language of which JavaScript is a dialect.
  • "Number.isInteger/toInteger": This looks like shorthand for two object / method names.

Scrolling through the bug comments, we eventually come to a link to the mozilla-central source-code repository:  https://hg.mozilla.org/mozilla-central/rev/0ac60eea3e4a

Investigating the source code in the bug

Following the link shows the changes that were made in the source code. The description of the change ("add Number.isInteger and Number.toInteger") confirms that this is indeed a change to the Number object. It adds the isInteger and toInteger methods.

The third link in the list of changed files points to the relevant change in the source code (jsnum.cpp). (The other two links point to files that contain test cases.)

Scrolling down, we see the actual change itself. A comment tells us which version of the ECMAScript standard implemented the change ("// ES6 draft ES6 15.7.3.12"). If we search the internet for "ecmascript harmony number isinteger" we find the descriptions of the isInteger and toInteger methods in the ECMAScript Harmony specification. This is the reference on which we can base our changes in MDN.

Changes on MDN

In MDN, we search for the JavaScript Number object. In the Methods section of that page, we add the isInteger and toInteger methods. We note that the methods were added in version 16 of Firefox by changing the compatibility table.

In the Firefox 16 for developers article on MDN, we note that these methods have been added to the Number object.

Updating Bugzilla

Now that MDN has been updated to include the changes from the bug, we will update Bugzilla so people know what changed:

  • Remove the "dev-doc-needed" keyword.
  • Add the "dev-doc-complete" keyword.
  • Add a comment to the bug that includes links to any MDN pages that were changed.

Document Tags and Contributors

Tags: 
 Contributors to this page: jswisher, fscholz, williamr, jenzed
 Last updated by: jswisher,