mozilla.org content and cvs
by Mike Shaver <shaver@netscape.com>,
Terry Weissman <terry@mozilla.org>,
and Jamie Zawinski

Important things you should know about adding content to a subtree of the mozilla.org website follow. Read them, know them, become one with them, for if you break your section of the website, you will have only yourself to blame. (Unless our instructions suck, of course, in which case we'll have to help you fix it, and you may mock us mercilessly.)

1. All files that are checked in to the CVS repository anywhere under the html directory will be visible on the web site.

2. By default, HTML files will have the standard mozilla.org left-edge menu appended to them; those HTML files listed in the NOWRAP file in the same directory will not be wrapped. (Only HTML files will ever be wrapped, so you needn't list images in NOWRAP.)

3. You must ``cvs add'' everything, and you should follow all the other rules of good CVS hygiene as well, such as properly tagging binary files with -kb to avoid corruption, etc.

4. In general, you are expected to behave responsibly, and to not modify files that you know nothing about.

   There are a few files (in particular, mozilla-org/html/index.html and mozilla-org/html/news.html) that are tightly controlled; any attempt to check in changes to these files will fail. If you really need to make a change and the system refuses you, send mail to webmaster@mozilla.org.

5. When adding or removing files, or altering the NOWRAP file in any way, you must ensure that running ``gmake'' from the top-level directory completes successfully. This will regenerate the Makefile to take into account the new files.

   If you do something that horks the ``make'' process, then no new content can show up anywhere on mozilla.org until it is fixed. Breaking things in this way is therefore a fairly big deal, so don't do it.

   You wouldn't check in source code without making sure it compiled first, would you? Of course not. This is the same situation.

   You will need perl5 to be in your path (perl5.004 seems necessary, on Solaris at least). Check out the entire mozilla-org hierarchy, and then run gmake from the top-level mozilla-org directory (the one with the Makefile in it). The munged files will be created in the output subdirectory.

   Special note to non-Unix people: All of the magic was written by a bunch of Unix heads. However, we have since made efforts to make this work on other OS's, too.

   On Win32 machines:

   • If you can't get gmake to work, just run "perl5 tools/munge.pl".
   • It's up to you to find a working perl5 for your system. We really have bent over backwards to stop using Unix-dependant things.

   On Macintoshes (thanks to John McMullen):

   • To run the munge.pl script on Macintosh, first run MacPerl. Then select "Run Script.." from the Script menu, and browse to munge.pl, which is in the tools subdirectory of the mozilla-org directory.
   • If you compile the entire mozilla-org site, the script will use a lot of memory. We suggest increasing MacPerl's "Preferred Memory" size to 8MB. However, if the script does run out ot memory, it will simply print a diagnostic, and not crash. Then you can run it a second time, and it will figure out where it left off and carry on processing.

   If you have suggestions for further improvements to make things more friendly to non-Unix systems, please send mail to terry.

6. ``gmake fascist'' will do some superficial checks on all of the files to check lack of conformance with the style guidelines in README-style.html.

7. A staging script runs every n minutes (n is currently 5) on www.mozilla.org to make the CVS-committed content visible to the waiting hordes.

8. The CVS repository is accessed in one of two ways: with ``ssh'', or with ``pserver.'' Whoever created your account should have told you which one you are to use. (If you still don't know, ``pserver'' is a good guess.)

   • To use pserver:
     Make your $CVSROOT variable be:
     :pserver:your%address@gila.mozilla.org:/cvsroot

   • To use ssh:
     Make your $CVSROOT variable be:
     your%address@gila.mozilla.org:/cvsroot

     You should also set your $CVS_RSH to ``ssh'', and make sure that you have

     Host gila.mozilla.org
        Port 24
     

     in your .ssh/config.

   Where it says your%address above, you would substitute your canonical email address, but replacing the ``at'' character (@) with ``percent'' (%). For example, if your email address was foo@bar.com, your $CVSROOT would be either:
   

   	:pserver:foo%bar.com@gila.mozilla.org:/cvsroot
   or	foo%bar.com@gila.mozilla.org:/cvsroot

   Once $CVSROOT is set properly, check out using

   cvs -z3 co MozillaOrgTrim

   The -z3 is to compress things during transit. -z3 seems optimal. The MozillaOrgTrim module checks out a partial version of the web site that's missing some of the larger pieces. The MozillaOrg module checks out the entire web site. Other modules include Newlayout, Documentation, Grendel, MathML and Quality. For a complete list of modules type:

   cvs co -c

9. Your files should look like the ones in the html directory, in that they should have only your content, and not the menu bar hackery. The menu bar hackery gets added through the dark magic of Perl.

10. If you want something added to the left-side menu, you have to ask One Of Us to do it, at least until we figure out a better system. (If you want to go off and figure out such a better system, that would be great: all the current magic is in the Makefile and the files it references, especially template.html.)

Good luck...