This is in response to some of the ideas I've seen while skimming
through the (very large) "Summary..." thread on m.d.general.

I propose migrating the documentation about getting started with Mozilla
development from mozilla.org into the MDC wiki's "Developing Mozilla" area:

http://developer.mozilla.org/en/docs/Developing_Mozilla

I can do the initial migration work, starting with the "Hacking Mozilla"
handbook (and related subdocs), here:

http://www.mozilla.org/hacking/

Once in the wiki, of course, it would then be much easier to update,
(re)organize, and maintain.  As necessary, "official" docs, such as
"Drivers" and "Super-Reviewers", could be locked so only people with
admin access on the wiki could change them.  (With admin access given to
whomever needs it to do those updates.)

If there are other related relevant-but-aging docs on Mozilla.org that
should be migrated (if this proposal is accepted), I'd be happy to do
those as well.

Please let me know if you think this is a good idea.  I'm happy to make
this a priority task for myself if it would be helpful.

~ deb

(Technically this is about mozilla.org development, so replies might
best go to m.d.mozilla-org.)

On 16-03-2006 21:34 CET, Deb Richardson composed this enchanting statement:

Great. I called it the need for Open Documentation development in one of
the Mozilla support newsgroups.

I am sure you will get a lot of help with this initiative, hopefully
also from experienced software documentation profs, being retired
looking for a hobby. I'm subscribed here. I'll spread the word if the
lights are green.

--
Kind regards,

Melchert

MacOS 10.3.9/Firefox 1.5/Thunderbird 1.5

This sounds like a great idea. If you need (or would like) help from the
Mozilla Foundation side please let me know.

I agree that this is desirable.

There are also some policy-related documents that it might make sense to
include in this migration, again with appropriate access control. These
might nclude the policies relating to CVS committers, licensing policy
(including how to use the license boilerplate files), policy on handling
security vulnerability reports, and others.

Frank

--
Frank Hecker
hec...@mozillafoundation.org

I've gone through the Hacking Guide and a bunch of the documents to
which it links, and have came up with the following list:

http://developer.mozilla.org/en/docs/User:Dria:hacking_guide_migration

It's fairly extensive, and not necessarily final.  I would like some
feedback about what perhaps shouldn't be on that list, what might be
added, and which documents should (or shouldn't) be "locked" after
migration.  Anyone is welcome to edit the list, using the "Edit" link in
the right hand column.

If that list seems OK (or at least mostly OK), let me know and I will
get started on the migration work as soon as possible.

~ deb

What do you mean by "migration"?

One problem mozilla.org has is that there are often a lot of pages that
have similar material. If we create a new official location we should
immediately go forward and archive all the old pages somewhere, and mark
them with big flashing red "OBSOLETE".

I'm interested in the usability of the pages users see when they want to
get involved. In addition to looking at what we already have, I think we
should also look at some other successful open source projects with god
web sites and try and map out our content and theirs.

Once someone has decided to contribute to a Mozilla project development,
a page with a set of link to pertinent areas:

- projects: different (active!) projects
- testing info: nightly builds,
- discussion lists: how to participate in development discussions
- contacts: who to ask
- getting and building the source
- contributing code: process from bug to maintenance
- bookmarks: important links for contributors (tbox, bugzilla, lxr, etc)

A few important links to other material on mozilla.org

- mozilla's mission
- project organization/leadership - different groups, and how exception
handling works.

The key is to keep these pages trim, have them contain only the material
folk need to get at when they're getting started.

The mozilla.org page should over time diminish the size of the
Firefox/Thunderbird box at the top (maintaining the link off to
mozilla.com).

The mozilla.org page could look like this:

mozilla.org                          search [               ] ( Go )
                  / Products \ Support \ Store \ Developers \ About \

  ((((((((((     Firefox & Thunderbird --> mozilla.com     )))))))))

Projects:        Mozilla's mission is to preserve choice and
- Firefox        innovation on the Internet. You can help us build the
- Thunderbird    future of the Internet by _getting_involved_.
- Gecko
- Seamonkey      Existing contributors ...
- Camino
- Bugzilla       Announcements:     MozillaZine News:
   ...            * kjldfjsdf        * sdfkl;skd;lflk;df
                    ;sdlkf;slkf        sdflkdf;lsdffd

Community Blogs : Site Map : Security Updates : Contact Us : Foundation

-Ben

On Friday 2006-03-17 15:46 -0800, Ben Goodger wrote:

No need to archive or signpost; just add an HTTP redirect!  I think many
of the people migrating docs to devmo have been good about this; I've
had to clean up after some and add redirects, though.

I thought http://www.mozilla.org/hacking/ was about the clearest list we
had of the important documents, although in a subset of the categories
you list.  It's had a few additions recently that may not belong at
toplevel, though.

If they can be more useful to existing contributors and still be useful
to newcomers, that would be better.  It would also have the advantage
that the current contributors (who know what's correct and what's out of
date) would look at the pages intended for newcomers, which would mean
they would be more likely to be kept up to date.  But I definitely agree
that it should be easier for people to find information when getting
started.

It might even be good to have short descriptions in the "Projects" list
there:

Firefox
  Web Browser
Thunderbird
  Email Client
Gecko
  Web page handling, core of other apps
etc.

-David

--
L. David Baron                                <URL: http://dbaron.org/ >
           Technical Lead, Layout & CSS, Mozilla Corporation

application_pgp-signature_part < 1K Download

By "migration" I mean "move the content into the MDC (devmo) wiki as a
set of pages in the "Developing Mozilla" category, and redirecting the
original URLs to the new locations.

Once in the wiki, it will be much easier to update, reorganize, or add
to those pages.  Ideally they would be put together as a "Getting
Started" page for the "Developing Mozilla" section of the MDC.

As dbaron points out, we can just redirect the pages.  BSmedberg has
already done this with a fair chunk of the Building Mozilla
documentation, as you can see here:

http://www.mozilla.org/build

Agreed.  That's pretty much I envision for the "Getting Started" page.

Absolutely.  I think Step One would be to get the existing information
into the MDC wiki so it can be more easily updated.  Once in the wiki,
it will be much easier to work on reorganizing the content into a
focused "Getting Started" area for new contributors.

~ deb

OK. Do we care about cvs revision histories?

I was thinking the list I presented above might be a good surrogate for
the hacking page. The order of docs on the hacking page is a bit
haphazard, and the content not necessarily presented in the best way.

For example:

Life Cycle of a Patch (the top link):

The description on the Hacking page says "An overview of how to get the
source, develop patches, get them reviewed, super-reviewed and checked
in the tree."

Speed readers will skip the first paragraph that links to docs on
building from source (oops!), and a long document on hacking Mozilla.
They'll skip down to a section that includes links mostly on things to
consider before submitting patches for review/reviewing others' patches:
portability, l10n, etc.

I don't know if this is the ideal flow. I think the trick is to think
like a new contributor and their needs during the various stages of
their involvement: idea -> design -> coding -> review -> checkin ->
maintenance.

During the idea/design phase, mailing lists are very useful.
During the coding phase, docs about mozilla
architecture/conventions/portability etc useful.
During the review phase, docs about process, conventions, etc useful.
During the checkin phase, links to tinderboxen, regression policies, etc.
During the maintenance phase, handling bugs, etc.

I think most of the docs under hacking/ need to be refactored. Very many
contain large tracts of text that are redundant with other docs. More
bite sized pieces that are better organized would be more useful to
people. A lot of people want to help, but they may not have the patience
to read through many essays.

Let me come up with something more concrete and post it in this thread.

Absolutely.

Yes. This might be a way to kick-start some interest in some of the more
dormant projects too!

-Ben

No.

--BDS

Look at the list of activities and areas I gave in my other post in this
thread:

- projects: different (active!) projects
- testing info: nightly builds,
- discussion lists: how to participate in development discussions
- contacts: who to ask
- getting and building the source
- contributing code: process from bug to maintenance
- bookmarks: important links for contributors (tbox, bugzilla, lxr, etc)

As people become involved what are the things they're most likely to be
interested in? Getting involved with a particular project probably.

- Project List
- Discussion lists - the first port of call. Few people are going to
jump right in and start coding I bet, they probably want to see what's
going on first.
- Testing info - many folk get involved through testing, since
installing nightlies is an accessible entry point.

Next, once you're more adventurous:
- build from source
- contribute code (* this is a page in and of itself *)

Lesser importance right away, but useful if you need it:
- Links to tools (tbox, etc)
- Contacts: who do I ask? Help I found a security bug! Something is
wrong! etc.

For existing contributors what do they want?
- To know what's going on globally and in other parts of the world
- Links to documentation and best practices
- Links to tools
??

(* Contributing Code *)

What sort of code do people contribute?
- bug fixes for filed bugs (improving overall quality)
- new features/self-found bugs (scratching itch)

The process for handling the two is often very different. There's
usually little resistance to those producing bugfix patches. But a new
feature? Well, that requires discussion, design, and a lot more work.
How does that process work? Who decides if the feature should be
accepted? What goes where? etc. There's not really any material on that
stuff right now.

-Ben

This is also different per-project. Which raises the question, how do
these docs scale across projects?

-Ben

While I'm here, I should add that I think this is a nice set of
developer docs for engineering contributors:

http://subversion.tigris.org/hacking.html

What I like about this page is that it's clearly designed to be read by
engineers: nicely organized into bite sized chunks, smallish paragraphs,
bulletized items, etc. You get the feeling you're acquiring lots of
useful knowledge rapidly when you read it.

(Mozilla's large enough that each block might be its own separate page
(although a printable PDF guide for bedtime reading is a nice idea!))

-Ben

Using your ideas as a guide, and looking through our existing docs, I've
cobbled together a quick initial structure:

* Community, roles and responsibilities
** Includes lists of Drivers, Super-reviewers, Module owners, Security
team, etc.
* Projects
** Includes a list of all active projects, with related discussion
lists, wiki.mo links, and contacts
* Testing & Bug reporting
** Testing
** Filing bugs
** Handling security bugs
* Source code
** Getting the source
** Building from source
* Coding
** Fixing bugs
** Developing new features
** Contributing code
** Code review process
** Commit access
** Tools (bonsai, tinderbox, lxr)
** Theory and documentation
** Tree layout
** Coding style
** Coding conventions
** Secure coding guidelines
** Performance and leaks
* Maintenance
* Localization

Please fill in whatever you thinks missing or restructure it however you
  think it would best work.  We'll likely have to fill in some blanks
since our current docs don't cover everything we'll want in the guide.

~ deb

_Ben Goodger_ spoke thusly on 17/03/2006 6:46 PM:

Should the support section be moved to mozilla.com?
--
Chris Ilias
mozilla.test.multimedia moderator
Mozilla links <http://ilias.ca>
(Please do not email me tech support questions)

I'm wondering why you put "Tools (...)" and every subitem after that
*after* the process of developing a bug. I would say some/most/all of
these resources are very useful, if not indispensable, when starting
work on the code. How are you supposed to write a patch if you don't
know where what code belongs, how it should be styled, etc. (and maybe
something about how XPCOM/XPConnect work/are used (does that go in
Theory and documentation? I assume so...)).

When I came to one of the Mozilla projects about one and a half year
ago, the first thing I was taught to use was Bugzilla (where do I file
my bug?), next up was LXR (where is the code that I need to fix?), then
CVS and how to use it to create a patch. Security and leaks weren't of
much concern in that case, considering the nature of the fix, but if
they would have been, surely they would have to be considered before
trying to make the actual patch and getting it checked in?

-- Gijs

Just my luck. Obviously I meant "developing a fix for a bug".

-- Gijs

The Mozilla Corporation does not support Camino, SeaMonkey, tier-2
platforms, probably not XULRunner yet, etc. -- there is most definitely
a need for a mozilla.org support section.

Look at the list of activities and areas I gave in my other post in this
thread:

- projects: different (active!) projects
- testing info: nightly builds,
- discussion lists: how to participate in development discussions
- contacts: who to ask
- getting and building the source
- contributing code: process from bug to maintenance
- bookmarks: important links for contributors (tbox, bugzilla, lxr, etc)

As people become involved what are the things they're most likely to be
interested in? Getting involved with a particular project probably.

- Project List
- Discussion lists - the first port of call. Few people are going to
jump right in and start coding I bet, they probably want to see what's
going on first.
- Testing info - many folk get involved through testing, since
installing nightlies is an accessible entry point.

Next, once you're more adventurous:
- build from source
- contribute code (* this is a page in and of itself *)

Lesser importance right away, but useful if you need it:
- Links to tools (tbox, etc)
- Contacts: who do I ask? Help I found a security bug! Something is
wrong! etc.

For existing contributors what do they want?
- To know what's going on globally and in other parts of the world
- Links to documentation and best practices
- Links to tools
??

(* Contributing Code *)

What sort of code do people contribute?
- bug fixes for filed bugs (improving overall quality)
- new features/self-found bugs (scratching itch)

The process for handling the two is often very different. There's
usually little resistance to those producing bugfix patches. But a new
feature? Well, that requires discussion, design, and a lot more work.
How does that process work? Who decides if the feature should be
accepted? What goes where? etc. There's not really any material on that
stuff right now.

-Ben

This is also different per-project. Which raises the question, how do
these docs scale across projects?

-Ben

OK. Do we care about cvs revision histories?

I was thinking the list I presented above might be a good surrogate for
the hacking page. The order of docs on the hacking page is a bit
haphazard, and the content not necessarily presented in the best way.

For example:

Life Cycle of a Patch (the top link):

The description on the Hacking page says "An overview of how to get the
source, develop patches, get them reviewed, super-reviewed and checked
in the tree."

Speed readers will skip the first paragraph that links to docs on
building from source (oops!), and a long document on hacking Mozilla.
They'll skip down to a section that includes links mostly on things to
consider before submitting patches for review/reviewing others' patches:
portability, l10n, etc.

I don't know if this is the ideal flow. I think the trick is to think
like a new contributor and their needs during the various stages of
their involvement: idea -> design -> coding -> review -> checkin ->
maintenance.

During the idea/design phase, mailing lists are very useful.
During the coding phase, docs about mozilla
architecture/conventions/portability etc useful.
During the review phase, docs about process, conventions, etc useful.
During the checkin phase, links to tinderboxen, regression policies, etc.
During the maintenance phase, handling bugs, etc.

I think most of the docs under hacking/ need to be refactored. Very many
contain large tracts of text that are redundant with other docs. More
bite sized pieces that are better organized would be more useful to
people. A lot of people want to help, but they may not have the patience
to read through many essays.

Let me come up with something more concrete and post it in this thread.

Absolutely.

Yes. This might be a way to kick-start some interest in some of the more
dormant projects too!

-Ben

While I'm here, I should add that I think this is a nice set of
developer docs for engineering contributors:

http://subversion.tigris.org/hacking.html

What I like about this page is that it's clearly designed to be read by
engineers: nicely organized into bite sized chunks, smallish paragraphs,
bulletized items, etc. You get the feeling you're acquiring lots of
useful knowledge rapidly when you read it.

(Mozilla's large enough that each block might be its own separate page
(although a printable PDF guide for bedtime reading is a nice idea!))

-Ben

No particular reason.  I've moved the items around a bit, and posted the
structure on a wiki page here:

http://developer.mozilla.org/en/docs/Sandbox:Mozilla_Development:Gett...

Everyone is welcome to poke around there, comment on the "Talk" page
(via the "Discussion" link in the right-hand column), or even edit the
page itself.  I am not a Mozilla Developer, so I am relying on other
people's experience and expertise to guide the development of this
document structure.

Please, any feedback would be appreciated.

~ deb

On 3/21/06, Deb Richardson <d...@mozilla.com> wrote:
All in all, the list and order of topics to be covered seems to be
sane. I have a few comments though.

It's still a bit unclear who is the target audience of the Getting
Started guide. Is it supposed to be a guide for people new to Mozilla
project, as it name suggests, or just a handbook for mozilla
developers, as I could think looking at its TOC? I think we should be
careful not to mix the two, otherwise the end result may happen to be
suboptimal to both groups of contributors.

(Things like "handling security bugs", "Commit access", "Performance
and leaks" and list of drivers at the top doesn't seem to be
appropriate for the Getting Started guide. Topics such as QA and
Localization are not generally useful for developers, although I agree
that the Getting Started guide should advise a new contributor to get
involved in QA first)

Also it's not clear how the whole Getting Started guide will look. Is
it going to be a list of links like hacking page [1] now? IMO that's
not optimal, as a contributor has to read through multiple long pages
to learn the basics. For example, one shouldn't have to read the seven
pages of code review FAQ [2] just to request a review. (He'll have
time to read it while waiting for review anyway ;)

[1] http://www.mozilla.org/hacking/
[2] http://www.mozilla.org/hacking/code-review-faq.html

I would expect the Getting started guide to be a (relatively) concise
summary of the information we have, which is useful for new
contributors, with links to detailed explanations. Something like [3],
but not as detailed on technical topics, not as scary for chrome
developers, and with more pointers to existing information, such as
reviewers list.

[3] http://www.mozilla.org/hacking/coding-introduction.html

Nickolay

I'd be hoping to see that this document would evolve into something like
the js guide, from a structural point of view, and from the point of
view of target audience. I'm not that afraid that things get out of
scope if we don't define the target audience stricter. When it comes
down to the "js reference" part of this, we may want to link to pages
that are not on the wiki, or at least somewhat protected, for example
for the cvs committer form.

Axel

As the Apache folks say, +1 for migrating these and making them
accessible and editable.  Same for reorganizing them.  The current order
came about to help people find the content that had been there
previously, and so is definitely in need of fixing.

On the docs that should be locked, the few Deb has noted with "lock" are
documents we've considered official and so should be locked.  The other
official policy docs that should be locked are below.  Many need
updating very badly.  It would be helpful if there can be a way for
people to make suggestions (or provide an edited version that is clearly
marked as a proposed revision but not the official policy, if there is
wiki-fu that allows that).

  -- Policy on Handling Performance Regressions
     http://www.mozilla.org/hacking/regression-policy.html

[we may want to change or delete this old policy given current
development patterns.  But if we keep it as a policy it should be locked.]

  -- Mozilla Roles and Responsibilities
     http://www.mozilla.org/about/roles.html

  -- Handling Mozilla Security Bugs
     http://www.mozilla.org/projects/security/security-bugs-policy.html

         LOCK (?)

  -- Mozilla Modules and Module Ownership
     http://www.mozilla.org/hacking/module-ownership.html

   -- http://www.mozilla.org/projects/security/secgrouplist.html
[At least, I think this should be locked and maintained by an identified
person.  But it's not an official policy.]

mitchell