This is sort of a document describing how one can try to fix a bug for microb.

at least, in theory. Unfortunately, at this time, the web server is down. So
I'm writing it based on another web server which behaves approximately the
same.

Anyway, steps.
1. load http://timeless.justdave.net/mxr-test/garage/source/browser/

Mozilla Cross Reference garage
garage/ browser/

Search for: within this directory

view using tree: [ garage |v]
      Name     Size     Date (GMT)     Description
    Parent directory     -     Jul 13 11:44      
    browser-ui/     -     Jul 12 14:38      
    mozilla/     -     Jul 12 14:38      
    www/     -     Jul 20 12:11       

The code in question is part of mozilla (I know that, if you don't, the search
later will just be slower, that's fine, follow along for now).

2. click mozilla/
- http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/

       Name      Size      Date (GMT)      Description
    Parent directory     -     Jul 12 14:38      
    trunk/     -     Jul 12 14:34       

Not many choices. If you are worrying about branches, then you could use the
view using tree to switch to garage-all, that's an exercise for another day
(and it requires javascript, which I don't use)
3. click trunk/
- http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/

       Name      Size      Date (GMT)      Description
    Parent directory     -     Jul 12 14:34      
    extensions/     -     Jul 12 14:33      
    libgtkembedmoz/     -     Jul 12 14:33     Mozilla Web Engine.
    libidl/     -     Jul 12 14:33     library for parsing CORBA IDL files
    microb-browser/     -     Jul 12 14:34     Meta-package for MicroB Browser
aplication
    microb-eal/     -     Jul 19 11:06     MicroB Web Engine.
    microb-engine/     -     Jul 20 12:11      
    microb-l10n/     -     Jul 12 14:34     Localization package for
microb-engine 

We're going to have to make two changes, one's to localization, and one's to
the engine. In general, if you don't know where something is and you can see
words relating to it, you're going to want to start by hunting through the
localization.

4. click microb-l10n/
-
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-l10n/

     Parent directory      -      Jul 12 14:34       
     debian/      -      Aug 15 16:28      The Debian Package microb-l10n
    l10n2/     -     Aug 15 16:28       
    manifest/     -     Jul 12 14:33      
    get_latest_cvs_l10n.sh     244     Jul 12 14:34      
    l10n.tar.gz     6602k     Jul 12 14:34      

debian/ contains build scripts and descriptions and stuff. If you're from a
debian background you know it better than I do. If you aren't, I recommend you
read about it at debian.org, you'll quickly know more about it than I want to.

manifest/ is a gecko packaging thing which basically describes individual
packages (localization instances, extensions, themes, applications). You can
easily learn more about this than I know from developer.mozilla.org or
xulplanet.com

neither of these are what we want, so that leaves
l10n2/ this is just a poorly named directory, and it's what we want.
l10n.tar.gz is basically an archive of the CVS repository from which we
retrieved (see get_latest_cvs_l10n.sh) the baseline strings so that we can
recognize changes later and do evil things (see debian/rules)

5. click l10n2/
-
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-l10n/l10n2/

Well, if you're lucky you can limit your searches to a single localization,
preferably the one you recognize. The one I recognize is en-US. I'm not going
to actually paste the full list, there are about a dozen directories and a
manifest file for each.

6. click en-US/
-
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-l10n/l10n2/en-US/

only one choice
7. click locale/
-
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-l10n/l10n2/en-US/locale/

two choices, at this point you would have to know more about mozilla than you
should. so we'll stop here and review the ui.

Mozilla Cross Reference garage
garage/ browser/ mozilla/ trunk/ microb-l10n/ l10n2/ en-US/ locale/

Search for: [                   ] within this directory

view using tree: [ garage |v]
      Name     Size     Date (GMT)     Description
    Parent directory     -     Aug 15 16:28      
    branding/     -     Aug 15 16:28      
    en-US/     -     Aug 15 16:28       

I've already hinted about view using tree.
and if you've been paying attention, the top bit is basically breadcrumbs.

that leaves Search for: [                   ] within this directory

We're looking for a string, probably if our bug was any good, one listed in
comment 0 (specifically in the actual results).

* See the build configuration used for this version.
* See the prefs config used for this version.

I happen to like "used for", so I'll search for that.

8. enter "used for" in the search field
9. press enter/click search
-
http://timeless.justdave.net/mxr-test/garage/search?find=%2Fbrowser%2Fmozilla%2Ftrunk%2Fmicrob-l10n%2Fl10n2%2Fen-US%2Flocale%2F&string=used+for

the output is fairly similar to find output (and in fact is essentially a
reparsed version of it, I might explain how to abuse those features in some
other bug)

Mozilla Cross Reference garage

Free-text search through the source code, including comments.
By default, this form treats all characters as literals.
Search strings can have a maximum of 29 characters.
Read the documentation for help with glimpse's regular expression syntax,

Search for: [ used for                     ] <submit>
            [ ] Regular Expression Search
            [ ] Case sensitive
in files matching: [/browser/mozilla/trunk/microb-l10n/l10n2/en-US/locale/]
Suggestions from our users: [ none of these |v]

Limit output to pattern: [            ]
Limit matches per file to: [          ]
using tree: [garage |v]

Searching these files.

Found 3 matching lines in 3 files
used for
/browser/mozilla/trunk/microb-l10n/l10n2/en-US/locale/en-US/global/about.dtd,

    * line 17 -- <!ENTITY about.buildconfig.afterLink "used for this version.">

/browser/mozilla/trunk/microb-l10n/l10n2/en-US/locale/en-US/global/netError.dtd,

    * line 13 -- <!ENTITY deniedPortAccess.longDesc "<p>Address specified is
for port not normally used for web browsing (e.g. <q>mozilla.org:80</q> for
port 80 on mozilla.org).

/browser/mozilla/trunk/microb-l10n/l10n2/en-US/locale/en-US/pippki/pref-masterpass.dtd,

    * line 9 -- <!ENTITY managepassword.asktimeout "If it has not been used for
">

Well, I lucked out. cool.

10. click "about.dtd"
-
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-l10n/l10n2/en-US/locale/en-US/global/about.dtd

This is one of the files I'm going to have to change. The next real question is
where are the others. It's a reasonable guess based on the XML-ness of this
file that I'll need to "fix" all the other localizations (in fact, I'll stick
the same English in for all of them, if external people want to contribute
suggestions, I'd welcome them in other bug, but do note that Nokia spends money
on its own localizations, so at some point they'll throw out my English and
probably your suggestion, but I hope someday public contributions of strings
could change that).

Back to the story, where's the other file I need to change?

We have two choices, we can either use this search page, since it clearly does
searching, or because things were so very fast we could go back to where we
branched and try to make the next search similarly fast. The garage-all svn
collection takes >8GB at present. The browser tree is only 250MB. So the wrong
search is very painful. I can't cheaply calculate the size of the garage tree
because it's just symlinks to portions of garage-all. You probably noticed the
symlink hints when you traversed the trunk/ directory, if you switched to
garage-all, you'd see the difference.

11. go back to step 3 and click microb-engine/
-
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-engine/
       Name      Size      Date (GMT)      Description
    Parent directory     -     Jul 12 14:34      
    microb-engine/     -     Jul 12 14:34     Netscape Portable Runtime Library
    tarballs/     -     Jul 12 14:34      
    build_non_deb.sh     2k     Jul 20 12:11      
    create.sources.diff.sh     908     Jul 12 14:34      
    create_orig.tarball.sh     269     Jul 12 14:34      
    microb-engine_1.0.3.orig.tar.gz     48678k     Jul 12 14:34       

You might be wondering where those random descriptions come from that you see
in the right column, they're pulled from a number of places, one of them is
debian/control inside the described directory. It happens to magically work
often enough to be fairly useful. In this case, it's actually wrong. since
there are 14 described packages and the primary one is buried in the middle.
Anyway. it's in the middle. It turns out that there's actually an enhancement
to the logic which I can apply to improve this. I'll do that, either before or
after I finish this patch/description.

Anyway, directory choices
tarballs/ doesn't sound very promising

12. click microb-engine/
-
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-engine/microb-engine/

13. click debian/
-
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-engine/microb-engine/debian/

We landed in a debian/ directory, if you've already read about debian/
directories you know that they contain build instructions and patches. It seems
we're looking for a patch.

    configs/     -     Aug 15 16:28      
    patches/     -     Aug 15 16:28      
    prefs/     -     Aug 15 16:28      
    resources/     -     Jul 12 14:34       

As it happens, we could also be looking for a file in resources/ the reason to
guess that it's in patches/ and not resources/ is that the file we're changing
is for about:, and if you've used firefox or mozilla you'd know that about:
looks about the same in their too, so most likely the people who made microb
just patched it. (about:config otoh was a complete rewrite, it's in resoures/)

13. click patches/
-
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-engine/microb-engine/debian/patches/

two many files, time to search, but for what?
well, the line that matched was:
<!ENTITY about.buildconfig.afterLink "used for this version.">

and we know we see the quoted part in the ui, so let's search for the other
part, "buildconfig.afterLink"

14. enter "buildconfig.afterLink" in the search field
15. press enter/click search
-
http://timeless.justdave.net/mxr-test/garage/search?find=%2Fbrowser%2Fmozilla%2Ftrunk%2Fmicrob-engine%2Fmicrob-engine%2Fdebian%2Fpatches%2F&string=buildconfig.afterLink
Found 2 matching lines
buildconfig.afterLink
/browser/mozilla/trunk/microb-engine/microb-engine/debian/patches/160_MICROB_about_fixes_lp0.diff,

    * line 56 -- <li>&about.buildconfig.beforeLink; <a
href="about:buildconfig">&about.buildconfig.linkTitle;</a>
&about.buildconfig.afterLink;</li>
    * line 57 -- + <li>&about.buildconfig.beforeLink; <a
href="about:config">prefs config</a> &about.buildconfig.afterLink;</li>

Wow, we found both the good line about:buildconfig, and the bad line. perfect,
so now we know which files we need to change and how to change them.

Point of order about bug management, since I think the bug is something I can
fix (since I've figured out what's wrong, and what to change to fix it), I'll
go to bugzilla and write a short explanation (that's this thing above, normally
your explanation will be much shorter).

But I should also take ownership of the bug. You might wonder who or what
nobody@maemo.org is. Basically it's an invitation for you to take ownership of
this bug, or any bug like it.

I want to own this bug.
But I can't just select (*) Accept bug (change status to ASSIGNED). That's a
feature that would enable a secretary or equivalent to accept the bug on behalf
of the current owner (nobody@maemo.org). Which I don't want.

Instead, I go down to Reassign bug to: [nobody@maemo.org        ]

I replace that with "timeless", why not timeless@gmail.com? because I'm lazy.
Bugzilla on well configured installations (which in this case includes
bugs.maemo.org) will try to figure things out for you when you enter incomplete
email addresses. 

16. enter "timeless"
17. If I have javascript enabled, I can click the web page to the right of the
text field - and bugzilla will automatically check the radio button:
(*) Reassign bug to

I don't.
18. click (*) Reassign bug to

If I don't do one of 17/18, the default action (*) Leave action as NEW will be
kept. (in the javascript case, clicking commit also works)

19. Click commit
If you don't click commit, it never happened.

One big word of warning, if you're writing a long essay in IE (or a crashy
browser, I'm using Minefield which sorta sounds crashy), you probably should
backup or compose your comments elsewhere [notepad]). When you click commit, if
someone has already made a non trivial change you might get a midair collision,
or if you've made a bad change, you could get an error. In IE, because the page
is a cgi/nocache/ssl, when you go back, it drops your hard written essay.

Minefield is crashy, but it has this cool thing called sessionstore,
unfortunately there's a setting browser.sessionstore.privacy_level (see
about:config) which defaults to 1, which means that it doesn't store form
information for SSL pages (bugzillas tend to configured to use SSL). So when
minefield crashes, unless you set that value to 0, you're just as out of luck
as ever.

One tip for people who are curious, you can enter "@" into the Add CC section,
it's guaranteed to trigger an error. Depending on how bugzilla is configured,
otherwise you may or may not get a page explaining what things are doing. and
if you, like me are composing using internal urls, you might want to have a way
to avoid accidentally committing early.

The result will look something like this:
Bugzilla was unable to make any match at all for one or more of the names
and/or email addresses you entered on the previous page.
Please go back and try other names or email addresses.

Assignee:     timeless matched timeless@gmail.com

CC:     @ was too short for substring match (minimum 3 characters)

When I get that, I just go back (since I'm not using IE), and since I'm now
ready, I remove the @ from add CC.

I'll be back with a patch after these messages.

Created an attachment (id=514) [details]
fix about: to include localizable text for about:config

btw, meet swift. If you ever see me accidentally include urls to swift, this is
it, it's my workstation and it also runs its own mxr, just like
timeless.justdave.net (which is back up now, although it's currently doing a
svn update, so while the result links will work, the search links won't until
the index updates)

1. make a sandbox
timeless@swift:~% pushd /tmp; mkdir 1831; cd 1831

Since this is svn (and you can do something similar with CVS), I'll only
checkout the pieces I need.
For git, Hg and friends, you'll need more disk space. But please, patches
against the VCS your project is using are always preferred over generic diffs.

2. How do I find the svn repository and what do I checkout?

I said this was svn, svn manages directories by including a .svn directory, so
let's try to add that to the directory we're interested in.
I'm going to have to change 160_MICROB_about_fixes_lp0.diff, so let's look for
a .svn directory for that file's parent directory:
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-engine/microb-engine/debian/patches/.svn/

    entries     39k     Aug 15 16:29       

Happens to be the magic file that svn uses. (CVS's directory is CVS/, and for
what you need in this case, you would look at Root and Repository)

Opening that file, I see:
   8   
url="https://garage.maemo.org/svn/browser/mozilla/trunk/microb-engine/microb-engine/debian/patches"

3. get sources-1
timeless@swift:/tmp/1831% svn co
"https://garage.maemo.org/svn/browser/mozilla/trunk/microb-engine/microb-engine/debian/patches"

the other one will be l10n2, since I'll need to change all the localizations
:(. If I'm not sure about the repository path, I can use the same trick to find
it. But I know that they're part of the same repository, so I'll just do it
directly:

4. get sources-2
timeless@swift:/tmp/1831% svn co
"https://garage.maemo.org/svn/browser/mozilla/trunk/microb-l10n/l10n2/"

You'll note that I'm making my string /slightly/ differently than the other
one. I couldn't come up with English that I liked that left the link in the
middle. The only way I found was to have the link as essentially the last word.
So, I cheated and offered a parenthetical. Since a localizer (including the
English linguist), might choose not to have any tail. I need some way to let
the sentence be:
* Change this application's internal settings.

If the space is not part of the localizable text, the result would be:

* Change this application's internal settings .

And yes, this is a bug in mozilla.org, I should report it.

Note that I used a bit of evil hackery to mass apply my English string. Stuff
like that is left as an exercise. In general, localizations don't actually want
you to do things like this, but each localization policy is different. (The
general policy of course, is "hands off".)

5. make the actual changes.

The last problem I had, was that I couldn't actually find any way to get svn
diff to give me full paths in its diff output. Which is really annoying. 

6. build diff

Here's what i did:
timeless@swift:/tmp/1831/l10n2% grep http .svn/entries
   url="https://garage.maemo.org/svn/browser/mozilla/trunk/microb-l10n/l10n2"
   repos="https://garage.maemo.org/svn/browser"
timeless@swift:/tmp/1831/l10n2% svn diff > 0
timeless@swift:/tmp/1831/l10n2% perl -pi -e 's#^((?:Index:|---|\+\+\+)
)#\1mozilla/trunk/microb-l10n/l10n2/#' 0
timeless@swift:/tmp/1831/l10n2% cd ../patches
timeless@swift:/tmp/1831/patches% grep http .svn/entries
  
url="https://garage.maemo.org/svn/browser/mozilla/trunk/microb-engine/microb-engine/debian/patches"
   repos="https://garage.maemo.org/svn/browser"
timeless@swift:/tmp/1831/patches% svn diff > 0
timeless@swift:/tmp/1831/patches% perl -pi -e 's#^((?:Index:|---|\+\+\+)
)#\1mozilla/trunk/microb-engine/microbengine/debian/patches/#' 0
timeless@swift:/tmp/1831/patches% cd ..
timeless@swift:/tmp/1831% cat */0 > 1831

7. load the bug: https://bugs.maemo.org/show_bug.cgi?id=1831

8. click "Create a New Attachment"
- https://bugs.maemo.org/attachment.cgi?bugid=1831&action=enter

9. select the file (if you're doing development work on a different box as I am
and have a windows browser you can enter a URL to a web server that contains
the patch, windows will download the file for you to a temporary place and give
the temporary path to the web browser [minefield])

10. give it a description
Description: fix about: to include localizable text for about:config

11. it's a patch
[x] patch

12. fill in the comment.

13. click submit

Last step if you're me is to write a decent checkin comment, and commit.

I tend to use bug summaries as part of my checkin comments. In this case, I
chose to rewrite the summary because the original summary was written by
someone complaining about a problem. And I want the summary to describe the
fix.

So, I'm going to change the summary, write this comment, select

(*) Resolve bug, changing resolution to [FIXED |v]

and click commit

Something I've always done is to prefix my SVN commit messages with the number
of the bug it fixes. Makes it that much easier to find later on. Unless you've
customized SVN to have a custom field for the bug number (which I'm working on
doing myself at work).

I should have been clearer on that point. Anyway, supposing you wanted to see
the comment I used, you could go to any of the files I changed in the cross
reference, e.g.:
http://timeless.justdave.net/mxr-test/garage/source/browser/mozilla/trunk/microb-engine/microb-engine/debian/patches/160_MICROB_about_fixes_lp0.diff

And then click "VC Log"
https://garage.maemo.org/plugins/scmsvn/viewcvs.php//mozilla/trunk/microb-engine/microb-engine/debian/patches/160_MICROB_about_fixes_lp0.diff?root=browser
--
Bug 1831 make description for about:config localizable

includes engineer's English for all localizations
--
So yes, I always include the bug number.