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: 323719
  • Created:
  • Creator: jenzed
  • Is current revision? No
  • Comment

Revision Content

moved to https://developer.mozilla.org/en-US/docs/Project:About

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 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 tracker is a front-end to Bugzilla that makes it easy to find bugs that require updates on MDN.

Bugzilla

Your search on the MDN Doc bug tracker 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

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

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 but 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

<div class="note">
  <p>moved to https://developer.mozilla.org/en-US/docs/Project:About</p>
</div>
<p>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.</p>
<h2 id="A_JavaScript_Update">A JavaScript Update</h2>
<h3 id="MDN_Doc_bug_tracker">MDN Doc 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 easy to find bugs that require updates on MDN.</p>
<h3 id="Bugzilla">Bugzilla</h3>
<p>Your search on the MDN Doc bug tracker 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>. 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 suggests 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 object / 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 id="Source_code">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. It adds 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 links point to files that 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 id="MDN">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 but 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 id="Update_Bugzilla">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>
</ul>
Revert to this revision