Skip to content

dineshkummarc/gnomeweb-wml

Repository files navigation

                    A brief primer about gnome-web hacking.

   gnome.org  hosts many Web sites. The source for the sites are in GNOME
   SVN in several modules. Each module contains one or more Web sites and
   a  method  to  generate  the  site. The long term goal is to unify the
   sites, both in presentation and how they are generated.

Web hacking tools

   SVN
          for  checking  out modules, updating code, creating patches and
          committing.

   build-tools
          for  generating  and  merging  content  with  style and include
          files.  The  most  important  tool  is make, which controls the
          tools are used to generate each page.

   patch
          for  applying  diffs/patches  to  update code with changes from
          other developers.

   editor
          for  making  changes. GEdit, vi, emacs, bluefish, and screem to
          name  a  few.  The  sites  use HTML, PHP, Perl, and shell--so a
          versatile editor that does syntax highlighting is practical.

   validator
          for  proving the your changes are correct. Tidy and xmllint are
          excellent,  and  can  even correct minor errors. The w3 hosts a
          validation service at validator.w3.org.

   Web Server
          for serving pages and running the applications.

   Web Browser
          for  viewing  the  changes.  Most modern browsers will will do,
          though Mozilla and Galeon provide the JavaScript debugger which
          can be useful.

   Bugzilla
          for  opening, updating, and closing bugs and enhancements about
          the Web sites.

Checking out the code

   The  GNOME  Web  sites  are  stored  in svn.gnome.org in gnomeweb-wml,
   web-devel-2, and foundation-web modules, as too are lxr (svn), bonsai
   (svn), and bugzilla:

   CAPTION: SVN module location of GNOME sites

           Site             Module
   www.gnome.org        gnomeweb-wml
   foundation.gnome.org foundation-web
   developer.gnome.org  web-devel-2
   guadec.gnome.org     guadec-web
   svn.gnome.org        bonsai and lxr
   bugzilla.gnome.org   bugzilla-newer
   mail.gnome.org       mail-web

   Instructions for using GNOME SVN are located at [1]developer.gnome.org
   tools. Check out one, or all, of the modules out.

   Run,  at  the  top of each module, autogen.sh --with-http-prefix=HOST,
   where  HOST  is the base URL where you will access the test site. HOST
   may  be  like  http://wgo as was set in the host file example below. I
   have:

   CAPTION: Virtual host to gnome host mapping

           Site         Virtual host
   www.gnome.org        http://wgo
   foundation.gnome.org http://fgo
   developer.gnome.org  http://dgo
   guadec.gnome.org     http://ggo

   For  each  site within each module, cd into it, and type make to build
   the  test  site.  The  web-devel-2 module is an exception, cd into its
   content directory and run make.

Setting up the Web server

   I  recommend  setting up apache with vhosts, one for each Web site you
   wish  to  work  on.  Almost  Web  server  that will do, though PHP may
   require  configuration.  Consult  your  Web  server  documentation for
   specifics.  What  follows  are the basic steps I took QA my changes to
   the code.

   I added additional host names to my /etc/hosts file:
   127.0.0.1 autumn localhost wgo dgo fgo ggo lgo

   Check that the htaccess files are enabled in the apache httpd.conf:
   AccessFileName .htaccess

   Check that virtual host naming is enabled in the apache httpd.conf:
   NameVirtualHost *

   To the apache httpd.conf, add a section like below to for each virtual
   host. Note that developer.gnome.org is an excecption, its DocumentRoot
   is web-devel-2/html/:
   <VirtualHost *>
   DocumentRoot /home/chovey/Projects/gnome2/gnomeweb-wml/www.gnome.org/
   ServerName wgo
   </VirtualHost>

   Restart  Apache.  With  your  browser,  test that everything worked by
   visiting  each  site.  Using  the  setup  described above the location
   http://wgo/ should display the www.gnome.org homepage.

Making changes

   Make  your  changes  to  the site(s) using your editor. Issue the make
   command at the top of the site directory to regenerate the site to see
   your  changes.  The  make  program  uses  the Makefile.am file in each
   directory  to call a script that merges header, footer and CSS content
   with  the  source  page  to  generate  the final page. The scripts and
   included  content  are located at the top of the module in the scripts
   and include directories.

   If  you add files to a site, be sure to update the Makefile.am file in
   the  same directory with the file names. Makefile.am contains the list
   of  files  that  the make program must compile and/or generate for the
   site. If you create a directory, you must also create a Makefile.am in
   that  directory, and you must add that Makefile.am to the configure.in
   file  located  at  the  top  of  the module. You must rerun autogen.sh
   --with-http-prefix=HOST  to  make  file  and  directory additions take
   affect, and you must run make to see them.

   Moving  a directory will break sites linking to that URL. Breaking URLs
   is a bad thing for  search  engines,  bookmarks,  and linking sites. If
   an asset must move, a redirect should be setup in the htaccess file
   located at the top  of  the module. Note that the htaccess file is
   copied by the make program to the generated site as .htaccess.

   Some  older  PHP  application  require the true GNOME server to run so
   they cannot easily be developed.

   Good  markup  makes good pages. Please check that your work is free of
   errors.  Tidy,  from tidy.sf.org, is a HTML markup validator, cleaner,
   and  transformer.  Use the tidy -e command to check for errors. Errors
   may  come from your changes, the included, assets, or by their merger.
   Tidy's  cleaning  and  formating  features  can  be used, but they are
   limited since it cannot check the source file.

Committing changes

   If you created new files and directories, add them to SVN. Remove your
   deleted files from SVN. You should run 'svn up' at the top of the module
   to get the most recent changes from SVN. Be sure to check that none of
   your change show up as a conflict.

   Run   the  prepare-ChangeLog.pl  script  (from  [2]developer.gnome.org
   scripts)  at  the  top of the module. Update the ChangeLog file at the
   top of the module with your changes. The modules's maintainer can give
   you  permission  to  commit after the patch is reviewed. If you do not
   have commit rights, the maintainer or another member of the webhackers
   group can.

   To create a patch, run svn diff >
   module_name-your_name-fix_description.patch  at the top of the module.
   The  patch  should  be sent to the gnome-web-list to notify someone to
   review your changes. If you can catch the attention of a maintainer in
   #webhackers on irc, you can send the patch to them.

   If the fix is for a filed bug in bugzilla, then the bug number will be
   a  suitable  description  for  the  patch.  Please  update  the bug in
   bugzilla by attaching the patch and use the keyword 'PATCH' so that it
   can be found.

References

   1. http://developer.gnome.org/tools/svn.html
   2. http://developer.gnome.org/tools/scripts.html