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.)
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.
> 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.)
I agree that this is desirable.
> 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.
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
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.
> 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.
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.
> The key is to keep these pages trim, have them contain only the material
> folk need to get at when they're getting started.
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.
> 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
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
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.
> 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".
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:
> 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:
Agreed. That's pretty much I envision for the "Getting Started" page.
> The key is to keep these pages trim, have them contain only the material
> folk need to get at when they're getting started.
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 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.
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.
>> The key is to keep these pages trim, have them contain only the material
>> folk need to get at when they're getting started.
>
> If they can be more useful to existing contributors and still be useful
> to newcomers, that would be better.
Absolutely.
> Firefox
> Web Browser
> Thunderbird
> Email Client
> Gecko
> Web page handling, core of other apps
> etc.
Yes. This might be a way to kick-start some interest in some of the more
dormant projects too!
-Ben
No.
--BDS
- 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
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
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
-- 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.
- 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
OK. Do we care about cvs revision histories?
> 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.
I was thinking the list I presented above might be a good surrogate for
For example:
>> The key is to keep these pages trim, have them contain only the material
>> folk need to get at when they're getting started.
>
> If they can be more useful to existing contributors and still be useful
> to newcomers, that would be better.
Absolutely.
> Firefox
> Web Browser
> Thunderbird
> Email Client
> Gecko
> Web page handling, core of other apps
> etc.
Yes. This might be a way to kick-start some interest in some of the more
dormant projects too!
-Ben
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
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:Getting_Started
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
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
These are a few documents I feel aren't really hacking process, but more
part of an "about this organization: its purpose, structure, organizational
policy, etc" section. (We have quite a few documents that would belong in
such a section, but there's no index page holding them together, see e.g.
bug 231131.)
http://www.mozilla.org/about/roles.html
http://www.mozilla.org/hacking/module-ownership.html
http://www.mozilla.org/about/staff
http://www.mozilla.org/about/drivers
We could move those over too, if you want, but I think once you cross that
line, almost everything else on www.mozilla.org might as well move too, and
the site's dead except as a redirect. Just something to consider.
http://www.mozilla.org/unity-of-interface.html is an editorial. We have
a handful of these scattered on the Mozilla site. I don't know what its
legal status is, but it's the sort of document that, I think, it would
be rude to change or edit without the author's permission even if we
legally own it.
http://www.mozilla.org/why/support.html isn't a developer doc imo. It
definitely needs updating, and probably a little editorial help, too.
Putting it in a wiki seems like a good way to get it updated, but I
think it /belongs/ on www.mozilla.org as an advocacy/PR document for
the organization. It's certainly not a hacking process document. Not
sure whether that makes it on or off the list. :)
~fantasai
We could do this as two related items.
The "Hacker's Guide" as it currently exists could be restructured,
rewritten, and expanded. This would be a larger "Guide" for more
experienced developers, and would be a direct replacement of the
existing Guide.
We could also write a proper "Getting Started" guide as you suggest -- a
more succinct and basic introduction to only the most important
information and concepts, specifically written for people absolutely new
to Mozilla development and the Mozilla community. This document
would/could form the Introduction section of the larger Hacker's Guide,
serving as an entry point to the various concepts presented there.
How does that sound?
~ deb
Sounds good. Thanks for replying.
Nickolay
Is there a document somewhere on doing this? I just discovered that I can
doctor .htaccess files, but that's not really very obvious at all...
-Boris
I'm not sure what you mean. That's a pretty standard way to do redirects
on Apache...
~fantasai
The point is that it's non-obvious that one can (or should) edit the .htaccess
file using Doctor. Further, it's non-obvious that Apache is what's running
here. And I had to steal a redirect line from another .htaccess file in our
tree that I guessed at (the other option would be to know about Apache and look
up docs, of course).
So basically, we should have a three-step "how to migrate a document" document.
IMO. If there's no such thing yet, I can write one up.
-Boris
So basically, we should have a three-step "how to migrate a document" document.
IMO. If there's no such thing yet, I can write one up.
There's this so far: http://developer.mozilla.org/en/docs/MDC:Needs_Redirect
The convention, IIRC, is to use a .htaccess in the deepest directory.
At least that's what I've been doing. We definitely want to keep most
redirects out of the root .htaccess.
~fantasai
Is it possible to do redirects on wiki.mozilla.org ?
I happen to have done some poor man's redirect there :
http://wiki.mozilla.org/Javascript_crypto
http://wiki.mozilla.org/ImportUserCertificates
http://wiki.mozilla.org/PopChallengeResponse
http://wiki.mozilla.org/GenerateCRMFRequest
http://developer.mozilla.org/en/docs/MDC:Existing_Content links to the
page above is page that is the one to link to, IMHO
Axel