How to resolve a dev-doc-needed bug

  • Revision slug: User:jenzed/How_to_resolve_a_dev-doc-needed_bug
  • Revision title: How to resolve a dev-doc-needed bug
  • Revision id: 316307
  • Created:
  • Creator: jenzed
  • Is current revision? No
  • Comment

Revision Content

This page describes how to update MDN to match the changes that were tracked in Bugzilla bug # 761495. Sometimes the comments and descriptions in bugs are obscure and mysterious. This page attempts to provide clues and hints on how to decode a bug and find out what needs to be changed on MDN.

A JavaScript Update

MDN Documentation 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 tracker is a front-end to Bugzilla that makes it much easier to find bugs that require updates on MDN. Your search might have returned bug # 761495.

Bugzilla

In Bugzilla, we see that bug # 761495 has the title: "(harmony:inthelpers) add Number.isInteger/toInteger." This suggest 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 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

Source code

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, adding 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 files 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

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 using the "fx_minversion_inline("16") template. (Why does the isNaN method have a page bug not the others?)

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

Update 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.
  •  

Revision Source

<p>This page describes how to update MDN to match the changes that were tracked in <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=761495" title="https://bugzilla.mozilla.org/show_bug.cgi?id=761495">Bugzilla bug # 761495</a>. Sometimes the comments and descriptions in bugs are obscure and mysterious. This page attempts to provide clues and hints on how to decode a bug and find out what needs to be changed on MDN.</p>
<h2>A JavaScript Update</h2>
<h3 id="MDN_Documentation_bug_tracker">MDN Documentation bug tracker</h3>
<p>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 <a href="http://beta.elchi3.de/doctracker/#list=fx&amp;version=" title="http://beta.elchi3.de/doctracker/#list=fx&amp;version=">MDN Doc bug tracker</a> is a front-end to Bugzilla that makes it much easier to find bugs that require updates on MDN. Your search might have returned <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=761495" title="https://bugzilla.mozilla.org/show_bug.cgi?id=761495">bug # 761495</a>.</p>
<h3 id="Bugzilla">Bugzilla</h3>
<p>In Bugzilla, we see that <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=761495" title="https://bugzilla.mozilla.org/show_bug.cgi?id=761495">bug # 761495</a> has the title: "<span id="summary_alias_container">(<span id="alias_nonedit_display">harmony:inthelpers</span>) <span id="short_desc_nonedit_display">add Number.isInteger/toInteger." </span></span>This suggest a couple of things:</p>
<ul>
  <li><span id="summary_alias_container">"(<span id="alias_nonedit_display">harmony:inthelpers</span>)"</span>: "Harmony" is a new edition of <a href="http://en.wikipedia.org/wiki/ECMAScript" title="http://en.wikipedia.org/wiki/ECMAScript">ECMAScript</a>, the parent language of which JavaScript is a dialect.</li>
  <li>"<span id="summary_alias_container"><span id="short_desc_nonedit_display">Number.isInteger/toInteger": This looks like shorthand for two method name</span></span>s.</li>
</ul>
<p>Scrolling through the bug comments, we eventually come to a link to the mozilla-central source-code repository:</p>
<pre>
<a href="https://hg.mozilla.org/mozilla-central/rev/0ac60eea3e4a" title="https://hg.mozilla.org/mozilla-central/rev/0ac60eea3e4a">https://hg.mozilla.org/mozilla-central/rev/0ac60eea3e4a</a></pre>
<h3>Source code</h3>
<p>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 <code>Number</code> object, adding the <code>isInteger</code> and <code>toInteger</code> methods.</p>
<p>The third link in the list of changed files points to the relevant change in the source code (<code>jsnum.cpp</code>). (The other two files contain test cases.)</p>
<p>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 <code>isInteger</code> and <code>toInteger</code> methods in the <a href="http://wiki.ecmascript.org/doku.php?id=harmony:number.tointeger&amp;s=tointeger" title="http://wiki.ecmascript.org/doku.php?id=harmony:number.tointeger&amp;s=tointeger">ECMAScript Harmony specification</a>. This is the reference on which we can base our changes in MDN</p>
<h3>MDN</h3>
<p>In MDN, we search for the JavaScript <a href="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Number" title="https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Number"><code>Number</code> object</a>. In the Methods section of that page, we add the <code>isInteger</code> and <code>toInteger</code> methods. We note that the methods were added in version 16 of Firefox by using the "<code>fx_minversion_inline("16")</code> template. <span style="background-color:#ffff00;">(Why does the isNaN method have a page bug not the others?)</span></p>
<p>In the <a href="/en-US/docs/Firefox_16_for_developers" title="/en-US/docs/Firefox_16_for_developers">Firefox 16 for developers</a> article on MDN, we note that these methods have been added to the <code>Number</code> object.</p>
<h3>Update Bugzilla</h3>
<p>Now that MDN has been updated to include the changes from the bug, we will update Bugzilla so people know what changed:</p>
<ul>
  <li>Remove the "dev-doc-needed" keyword.</li>
  <li>Add the "dev-doc-complete" keyword.</li>
  <li>Add a comment to the bug that includes links to any MDN pages that were changed.</li>
  <li>&nbsp;</li>
</ul>
Revert to this revision