Development:Coding - Revision history

Sardisson: update license block info for MPL2

2012-03-28T21:13:08Z

update license block info for MPL2

Sardisson: /* Project (Camino.xcodeproj) changes */ add a section for non-Gecko stuff

2012-02-16T07:57:41Z

Project (Camino.xcodeproj) changes: add a section for non-Gecko stuff

Sardisson: /* Coding for latest-OS-version features or using private APIs */ typo

2011-02-26T21:31:48Z

Coding for latest-OS-version features or using private APIs: typo

Sardisson: /* Code Style */ provide an example of the multi-line if statement case

2011-01-31T21:39:07Z

Code Style: provide an example of the multi-line if statement case

Sardisson: /* Code Style */ Make explicit additional bracing rules that Stuart claimed were in the style guide during the review for {{bug|550817}} but which weren't obvious; also stuff about cleanup/whitespace

2011-01-30T22:55:21Z

Code Style: Make explicit additional bracing rules that Stuart claimed were in the style guide during the review for {{bug|550817}} but which weren't obvious; also stuff about cleanup/whitespace

Sardisson: /* Code Style */ add the method declaration(?) to the sample, per stuart's instructions on how we're standardizing

2011-01-12T01:19:06Z

Code Style: add the method declaration(?) to the sample, per stuart's instructions on how we're standardizing

Sardisson: /* Testing your patch */ move this huge section to its own article, Development:Using Custom Profiles

2011-01-10T01:43:47Z

Testing your patch: move this huge section to its own article, Development:Using Custom Profiles

Sardisson: /* Testing your patch */ complete

2011-01-10T01:36:51Z

Testing your patch: complete

Sardisson: /* Testing your patch */ checkpoint for dinner

2011-01-09T22:48:46Z

Testing your patch: checkpoint for dinner

Sardisson: /* Setting breakpoints in external files */ in-progress; need to add delliott's section and -profile

2011-01-09T21:12:44Z

Setting breakpoints in external files: in-progress; need to add delliott's section and -profile

@@ Line 6: / Line 6: @@
 *[http://www.mozilla.org/hacking/mozilla-style-guide.html Mozilla Coding Style Guide]
-*[http://www.mozilla.org/MPL/boilerplate-1.1/ License block for new files]
+*[http://www.mozilla.org/MPL/headers/ License block for new files] (use the <code>/* */</code> style)
 ''Also link to [http://www.mozilla.org/hacking/ Hacking Mozilla] general intro somewhere in our contributor introduction''
@@ Line 68: / Line 68: @@
 ====New Files====
-If you add a new file, be sure to give it the appropriate tri-license license block from [http://www.mozilla.org/MPL/boilerplate-1.1/ http://www.mozilla.org/MPL/boilerplate-1.1/]; do not copy boilerplate from other files.
+If you add a new file, be sure to give it the appropriate MPL2 license block from [http://www.mozilla.org/MPL/headers/ http://www.mozilla.org/MPL/headers/] (in C/C++/Obj-C/Obj-C++ files, this is the <code>/* */</code> style); do not copy boilerplate from other files.
-For files added in <code>mozilla/camino</code>, the ”The original code” should be “Camino code.”  There are a few general exceptions to this:
+=====New Third-Party Code=====
-# Makefiles are often “just a lowly Makefile”
+If you are adding a new file from another source (including code you yourself have written but not written specifically for Camino)—for instance, when we include [[User:Wevah|Wevah]]’s [https://github.com/Wevah/Punycode-Cocoa punycode methods]—you should preserve the existing license blocks on the files.  (You should, of course, first check to make sure that the license of the external code is [https://www.mozilla.org/MPL/license-policy.html#Licenses_Compatible_with_the_MPL compatible with the MPL v2].)
-Unless you are working on Camino in a work-for-hire situation (or similar), the “Initial Developer” should be your name (optionally followed by your email address).  In a work-for-hire situation, the original author is typically your employer; check with your employer for the specifics of your situation.
+If you are adding an entire bundle of third-party code (e.g., [http://mxr.mozilla.org/camino/source/camino/sparkle/ Sparkle] or [http://mxr.mozilla.org/camino/source/camino/google-breakpad/ Breakpad]), Camino style is to include a [http://mxr.mozilla.org/camino/source/camino/sparkle/README README] file in the code's top-level directory containing the source repository and licensing information for the third-party code, along with a list of any changes made to that code in order to use it in Camino (this list should be updated any time the third-party code is touched or updated).  If the third-party code already includes a [http://mxr.mozilla.org/camino/source/camino/google-breakpad/README README] file, add a [http://mxr.mozilla.org/camino/source/camino/google-breakpad/README_CAMINO README_CAMINO] file instead.
-The copyright year should be the year you began working on the code in the file, even if it's not committed until the following year (e.g., you began developing the patch in December 2009 but the patch was not committed until January 2010).
+When third-party code (either a few files or an entire bundle of code) is committed, the commit comment must include information or references to the author of the code and the source repository, if available.  Make sure your committer is aware of this information.
 ==Testing your patch==

@@ Line 143: / Line 143: @@
 === Project (<code>Camino.xcodeproj</code>) changes ===
-Making project changes has to be done using Xcode (when adding, deleting, or moving files, as well as changing most build/compiler options)<!--, specifically when adding files-->. After making any project changes, simply diff the project file as well and include it in your patch (if you made any changes to build configuration or settings, be sure to diff <code>camino/config/</code> as well to pick up xcconfig changes). Please check to ensure that your project patches do not change the state of the Camino.app entries in the Camino and CaminoStatic targets (this is usually a problem with srcdir configurations).
+Making project changes has to be done using Xcode (when adding, deleting, or moving files, as well as changing most build/compiler options)<!--, specifically when adding files-->, using the copy of the project in the source directory.
 You should also verify that Xcode has not added “garbage” to any of the sections it modifies automatically, such as header or library search paths (this is most common with Gecko build products; see below).
 <!--
 (Removing files can be done by hand if you don't have the proper version of Xcode, but this isn't recommended because removing the obvious entries for files will still leave non-obvious entries in the project file and cause crashes/build failures.)-->
 ====Adding Gecko build products to Camino and the project file====

@@ Line 51: / Line 51: @@
 The spell-checker's <code>learnWord:</code> method is undocumented on Mac OS X versions older than 10.5, but it is the only way to achieve proper "learned spelling" integration with the Mac OS X spelling system. The code supporting Camino’s use of this method is [http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/camino/src/embedding/CHBrowserView%2BSpelling.mm&rev=1.1&mark=62-67#62 here] and [http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/camino/src/browser/BrowserWindowController.mm&rev=1.388&mark=4517-4525#4517 here].
-On Mac OS X 10.5, Camino also support building a [http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/camino/src/browser/BrowserWindowController.mm&rev=1.388&mark=4447-4490#4447 Language sub-menu] for switching spell-check languages.
+On Mac OS X 10.5, Camino also supports building a [http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/camino/src/browser/BrowserWindowController.mm&rev=1.388&mark=4447-4490#4447 Language sub-menu] for switching spell-check languages.
 Setting Spotlight metadata on files is still undocumented as of the 10.5 SDK. Our download listener code has [http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/camino/src/download/nsDownloadListener.mm&rev=1.39&mark=652-702#652 a very well-documented and commented example] of how to use a method like this safely while running on Mac OS X 10.4 and 10.5.

@@ Line 22: / Line 22: @@
      baz;
      zap;
+   }
+}
 </pre>
-When the condition is multiple lines, braces are required on the statement.  If the <code>if</code> statement had braces, the <code>else</code> statement must also have braces.
+When the condition is multiple lines, braces are required on the statement (with the opening brace on a line by itself).  If the <code>if</code> statement had braces, the <code>else</code> statement must also have braces.
 Braces for single statements are optional (and discouraged, but some still include them).

@@ Line 25: / Line 25: @@
+}
 </pre>
 Braces for single statements are optional (and discouraged, but some still include them).
 We explicitly have no style rule regarding the placement of <tt>*</tt>.  Aim to be consistent within a file in as much as the files are consistent.
 === Coding for latest-OS-version features or using private APIs ===

@@ Line 13: / Line 13: @@
 <pre>
-if (foo) {
+- (bip)updateBat
-  bar;
-  blam;
+  if (foo) {
+    bar;
-else {
+    blam;
-  baz;
-  zap;
+  else {
+}
 </pre>

@@ Line 78: / Line 78: @@
 Once you’ve written code and gotten it to compile, you need to test your patch to make sure it works (and works as expected).  There are several methods available that allow you to launch another Camino at the same time as your daily-use Camino and/or protect your daily-use profile from development builds.  Some methods may be more useful in certain situations than others.
-'''N.B''' Note that none of these methods currently handle the <code>org.mozilla.camino.plist</code>, which stores settings related to our Cocoa UI; both builds will read the file into memory (and write to it occasionally), and the last build to quit will win and stomp other changes written to the file previously.
+See [[Development:Using Custom Profiles]] for detailed explanations of the various methods.
 ==Setting breakpoints in external files==

@@ Line 99: / Line 99: @@
 ===Terminal===
 In the Terminal, you can set the same environment variable that Troubleshoot Camino uses:
 :<code>export CAMINO_PROFILE_DIR="AbsolutePathToDesiredProfileFolder"; open /path/to/Camino.app</code>
@@ Line 104: / Line 105: @@
 If you simply export the variable, any future launch of Camino from that terminal will use the specified profile location.
 ===<code>Info.plist</code>===
@@ Line 110: / Line 121: @@
 Somewhat similar to the Xcode method above, you can set a custom profile by changing the value of the <code>mozProfileDir</code> key in your Camino build’s <code>Info.plist</code>.  Specify a custom name (e.g., <code>CaminoDebug</code>) and Camino will use <code>~/Library/Application Support/CustomName</code> for the profile when launched.
-'''N.B.''' Because the <code>Info.plist</code> is regenerated periodically
+'''N.B.''' Because the <code>Info.plist</code> is regenerated periodically (every time Camino is rebuilt following a pull of new Camino code from the repository, every time Camino is rebuilt following a Gecko build ID change, and any time there are changes made to the <code>Info.plist</code> itself), the above change will have to be repeated often.
 ==Setting breakpoints in external files==

@@ Line 73: / Line 73: @@
 ====Contributors to Existing Files====
 If you have made substantial additions or changes to a given file in a patch, or if, over time, you have done so, be sure to add yourself (along with your email address) to the “Contributor(s):” section of the license block.
 ==Setting breakpoints in external files==
-Sometimes when debugging you will want to set breakpoints in files that are part of Camino, but not in the XCode project. For example, <tt>widget/src/cocoa/nsNativeThemeCocoa.mm</tt>. If you get an error about gdb not being able to find the file:linenumber, you will need to add the relevant shared library. Head to Run->Show->Shared Libraries... and set the Starting Level for the library to All. Which library to set it for depends on the file; for nsNativeThemeCocoa.mm, it is libwidget_mac.dylib. Turning off "Lazy Symbol Loading" in Debugger preferences may also help.
+Sometimes when debugging you will want to set breakpoints in files that are part of Camino, but not in the XCode project. For example, <tt>widget/src/cocoa/nsNativeThemeCocoa.mm</tt>. If you get an error about gdb not being able to find the file:linenumber, you will need to add the relevant shared library. Head to Run->Show->Shared Libraries... and set the Starting Level for the library to All. Which library to set it for depends on the file; for nsNativeThemeCocoa.mm, it is libwidget_mac.dylib. Turning off “Lazy Symbol Loading” in Debugger preferences may also help.
 ==Preparing a patch to submit for review==