Developer's corner

How to have write access to Subversion repository?

• create an account on Gna! and ask to join PhpWebGallery project on the member list page
• administrative project manager will receive a join request and once validated, the requester will have write access to Subversion repository
• configure tools (Linux, Windows XP)
• take a look at Branch and releases
• retrieve a Subversion working copy (follow indications from PhpWebGallery Subversion page on Gna!).

You’ll find documentation on internet. External links:

• Subversion official website
• Introduction à Subversion (french) by Julien Barnier
• How can I use cvs/subversion on windows with ssh authentication ?

Please make use of the Coding conventions before committing your work to the repository.

# working on trunk
$ svn co svn+ssh://plg@svn.gna.org/svn/phpwebgallery/trunk
$ cd trunk
$ vi feed.php
$ vi notification.php
$ svn diff feed.php notification.php
$ svn commit -m "- add new informations in RSS notification feed" feed.php notification.php
 
# working on branch 1.5
$ svn co svn+ssh://plg@svn.gna.org/svn/phpwebgallery/branches/branch-1_5 1.5
$ cd 1.5
$ vi include/functions_html.inc.php
$ svn commit -m "- bug 256 fixed: wrong tags for HTML menus" include/functions_html.inc.php

• must be written in english
• each line should not exceed 80 columns

Each commit log have a distinct paragraph for each modification done. Two paragraphs are separaterd with an empty line. Each kind of modification must be easy to understand just by reading the log.

The following example shows a commit log with several kind of modification. Of course, you wont ever have as many modification in a single commit, it’s just an example. Thanks to be rigorous enough for “bug XXX fixed:”, “merge -r?:? from ? into ? (bug ? fixed)”, “feature XXX added:”.

bug 205 fixed: advise to perform maintenance actions at the end of upgrade
process.

merge -r967:968 from branches/branch-1_5 into trunk (bug 220 fixed).

feature 147 added: add a menu to manage manually create_listing_file.php
on remote sites

new: "quick start" section in Administration>General>Instructions

improvement: long localized messages are in HTML files instead of $lang
array. This is the case of admin/help and about pages.

deletion: of unused functions (ts_to_mysqldt, is_image, TN_exists,
check_date_format, date_convert, get_category_directories,
get_used_metadata_list, array_remove, pwg_write_debug,
get_group_restrictions, get_all_group_restrictions, is_group_allowed,
style_select, deprecated_getAttribute).

Working with Branches adds a new level of complexity concerning code modifications. Code modifications are linked to new features, bug corrections and the potential reports. All these code modification are logically managed by the bug tracking system.

The following explanations are theoretical. Sometimes these rules will be broken.

• An evolution is always developed in trunk. Needs no report on stable branches.
• Where to correct a bug is a more complex question.
  1. If the bug is blocking, it must be corrected on the stable branch and reported on trunk.
  2. Not depending on its severity, if the bug correction requires few code modification, it can be corrected on the stable branch and reported on trunk.
  3. Else, the bug is corrected on trunk, thus it will be corrected on next stable branch.

Correcting the bug on trunk and then reporting the correction on the stable branch will work easily near the fork, in time. But far from the fork day, the correction might need manual modifications. In Pierrick’s opinion, correcting on the stable branch and reporting on trunk is a better solution. In Gweltas’s opinion, a bug must first be corrected on trunk and then possibly reported on the stable branch, thus avoiding regression. Deciding whether a bug should be corrected on stable branch and trunk or only on trunk is a matter of subjectivity, obviously. Same remark for answering the question “where must the bug be corrected first?”

In the bug tracker, status “resolved” means corrected and status “closed” means reported on trunk.

# report a correction from trunk to 1.5
$ cd 1.5
$ svn merge -r 930:931 svn+ssh://plg@svn.gna.org/svn/phpwebgallery/trunk
$ svn status # get informations
$ svn diff   # more detailed informations
$ svn commit -m "- merge trunc r930:931 into branch 1.5 (bug 198 fixed)"

# report a correction from 1.5 to trunk
$ cd trunk
$ svn merge -r 945:946 svn+ssh://plg@svn.gna.org/svn/phpwebgallery/branches/branch-1_5
$ svn status
$ svn diff
$ svn commit -m "- merge branch 1.5 r945:946 into trunk (bug 254 fixed)"

Sometimes a new feature requires modification in the database. A new table for instance. Since Novembre 24th 2005, a system make it possible to automatically send database upgrade scripts to other developers : upgrade_feed.php and install/db/*-database.php. You must not forget to report the database modification in install/phpwebgallery_structure.sql for new installations.

IMPORTANT: on a stable branch, once the first release has been "released",
database upgrades must be avoided unless there is no other workaround.
A database upgrade is a complicated work for users and a very complicated
work for release packager, often generating errors in the last release build
steps. Take database upgrades on stable branches very seriously.

1. find next available upgrade identifier in your install/db directory, let’s say 43, and create install/db/43-database.php. On trunk branch, upgrade identifiers are ascending integers. On a stable branch (branches/branch-1_4, branches/branch-1_5), identifier is the the concatenation of the identifier of the last upgrade script on trunk before fork point. If the last upgrade id before branch 1.6 is 14, then upgrade identifiers on branch 1.6 will be 14.1, 14.2 and so on. To make it clear, an example graph might be useful

                +--------------+
                | branch trunk |
                +--------------+
                       |
                       |     +------------+
                       |     | branch 1.6 |
                 43 => |     +------------+
                 44 => |           |
                       +-----------+
                       |           | <= 44.1
                       |           |
                 45 => |           |
                       |           | <= 44.2
                 46 => |           |
                       |           |
                       |           | <= 44.3
                       |           |
                 47 => |           |
                       |           |
                       |           |
                       |           |
                 48 => |           | <= 44.4
                       |           | <= 44.5
                 49 => |           
                       |
                 50 => |
                       |     +------------+
                 51 => |     | branch 1.7 |
                 52 => |     +------------+
                 53 => |           |
                       +-----------+
                 54 => |           | <= 53.1
                       |           |
                 55 => |           | <= 53.2
                       |           |
                       |           |
                       |           | <= 53.3
                       |           
                       |

2. script 43-database.php is a PHP script, and not a SQL only script. This mean you can do much more advanced operation than SQL let you do. Take 1-database.php as template:

   <?php
   // [standard header]
    
   if (!defined('PHPWG_ROOT_PATH'))
   {
     die('Hacking attempt!');
   }
    
   $upgrade_description = 'Just a beginning test';
    
   // +-----------------------------------------------------------------------+
   // |                            Upgrade content                            |
   // +-----------------------------------------------------------------------+
    
   list($now) = mysql_fetch_row(pwg_query('SELECT NOW()'));
   echo
   $now
   ."\n"
   .'This upgrade script is for test purpose only'
   ."\n"
   ;
   ?>

3. modify install/phpwebgallery_structure.sql consequently. Do it by dumping your database structure

   # "prefixTable" is the prefix you use for tables in your personal database
   $ mysqldump --user=<user> --password=<password> --add-drop-table --no-data <my database name> \
     | perl -pe 's{prefixTable}{phpwebgallery_}g' \
     > install/phpwebgallery_structure.sql

4. add/commit files to Subversion