Gallery1:Developer Guide
Coding Standards[ ]
Try as much as possible to follow the Gallery 2 Coding Standards.
Especially make sure you use full PHP tags:
Wrong: <? ... code ... ?> <?= "foo" ?> Correct: <?php ... code ... ?> <?php print "foo"; ?>
Updating Code with Subversion[ ]
Gallery now uses Subversion on the SourceForge site to maintain software revisions. You should first spend some time reading over the Subversion Documentation on the SourceForge website, and familiarize yourself with how SourceForge and Subversion work together. You'll want to have Subversion installed on your home computer so you can grab updated copies of the Gallery code and commit your changes.
Please refer to the Gallery:Using Subversion page for instructions on downloading the Gallery 1 code. If you've been using CVS in the past, you might find the Subversion for CVS Users appendix useful (from the O'Reilly Version Control with Subversion book).
svn checkout[ ]
First, you'll want to checkout a copy of the Gallery code. Note that the URL uses the HTTPS protocol. For the latest development code:
svn checkout https://gallery.svn.sourceforge.net/svnroot/gallery/trunk/gallery
If you just want to keep up to date with the latest stable code:
svn checkout https://gallery.svn.sourceforge.net/svnroot/gallery/branches/BRANCH_1_5_LEGACY/gallery
svn update[ ]
If you just did a checkout, then you're all set. But if some time has passed and you want to get the latest version of the code, then you can update it by going into the gallery/ directory where the code is located and running:
svn update
You'll see a response like this:
U index.php U albums.php U photos.php ...
This will get you the latest version of the code. Each file you receive will be marked with a letter telling you what Subversion had to do with it.
svn status,
svn diff[ ]
As you're editing, you can use svn status and svn diff to inspect which files you've modified and what the differences are.
svn commit[ ]
When all your changes are made, be sure to test your code. You should copy your code over to a working test website. Follow the #Unit_Testing_Guidelines (see below) to make sure you haven't unwittingly introduced any errors. Now you're ready to commit your changes back to the repository:
svn commit [ --username <your SourceForge Username> ]
This command will drop you into your text editor where you should add a message to the Subversion log. You could copy your new ChangeLog (see below) message, for example. You will then be logged on to the SourceForge Subversion server and prompted for your password. You can read the Subversion documentation for instructions on caching your username and password, or using SSH keypairs for authentication.
Updating the ChangeLog and Version Bumping[ ]
We track Gallery updates in the ChangeLog file. In order to keep tabs on who's running what version, we need to bump the version for each SVN commit... no matter how large or small.
This is the format of a Gallery ChangeLog entry:
2000-01-31 Bharat Mediratta <bharat@menalto.com> 1.3.4-cvs-b16
* A useful description of each change made goes here. For example:
Fixed error in getAlbumByName() in Albums.php. (Bug #765432)
* Use a separate asterisk for each change you make.
If you use (X)Emacs as your text editor, you can use C-x 4 a to generate a properly formatted and dated ChangeLog entry. You can set your e-mail address in your .emacs file as well:
(custom-set-variables '(user-mail-address "bharat@menalto.com"))
In between releases, we start counting "build" releases of the next version. So the first change after the 1.4 release will be 1.4.1-cvs-b1, and so on. Note that these numbers are completely free so don't be stingy about using them and bumping the version number. Even if you're just fixing a tiny issue, roll a new number so that when we communicate with our users we know exactly what version they are using and when they have problems.
In addition to noting the version in the ChangeLog, it needs to be changed in the Version.php file as well:
$gallery->version = "1.3.4-cvs-b16";
If you've made a change in the Config. Wizard that requires the config.php file to be rebuilt, you must also bump the Config. Wizard version so that Gallery can instruct users of older versions to re-run the Wizard:
$gallery->config_version = 34;
Finally, if your change includes a database restructuring (e.g. adding a new variable to the Album class), you must bump the Album Data format version, which will force an upgrading user to regenerate all of the album data:
$gallery->album_version = 8;
Bumping the album version number triggers Gallery to upgrade albums the next time they're accessed. So when you do this you'll also need to add code to the appropriate integrityCheck() methods in the class files to provide an upgrade path to your new data format.
Adding New Files[ ]
If you add or remove a file that is directly linked to by the user (rather than called with an include() or require() call, you must add the file to the $safe_to_include array in index.php. This security measure prevents bogus PHP code from being spliced in when Gallery is embedded in another application. Keep the list in alphabetical order.
$safe_to_include =
array("add_comment.php"
...
"my_new_file.php"
...
'view_photo_properties.php"
);
Also, make sure that the file permissions on the new files are set properly, as it is a hassle to change them once they are on the Subversion server. Most files should have 644 permissions (-rw-r--r--), but directories and executable scripts should have 755 (e.g. drwx-r-xr-x) permissions, with the executable bits set.
Branches and Release Versions[ ]
Collaborative development is an exercise in trust and restraint. Remember that you're making changes concurrently with other developers and that we're planning releases around current and future changes. In order to manage risk and increase reliability, we have a policy for when and where you can commit changes. It's in the best interests of the team for you to follow these rules.
As a developer, you will be assigned an area of responsibility (in this case Gallery 1, or possibly Gallery Remote). You can freely commit changes, improvements, etc. into the trunk branch of your area without checking with other developers. Since many people track Gallery from Subversion (we especially get a lot of beta testers using the repository), you should make great effort to leave the trunk in a working state at all times and heavily test changes that may lead to data corruption. If you feel like your work may lead to data corruption, or have any doubts at all, please first create your own private branch and do your work there. When your code has reached stability, you can merge trunk into your branch, make sure the merge was clean, and then merge everything back down into the trunk.
svn copy[ ]
To familiarize yourself with Subversion branches properly, you should read the Branching and Merging chapter from the O'Reilly Version Control with Subversion book. You might also be interested in the svnmerge, a small Python script which can help to simplify the svn merge command for you. A typical Gallery branch example follows, using svnmerge to keep track of revisions.
Subversion uses real directories to store its branches. You should place your branches outside of your main trunk development directory. In the example here, your branches will live one directory level up from your trunk checkout. Then you're ready to copy the trunk into your new development branch:
you@yourbox:~/code> cd my_gallery_trunk_directory
you@yourbox:~/code/my_gallery_trunk_directory> cd ..
you@yourbox:~/code> svn copy https://svn.sourceforge.net/svnroot/gallery/trunk/gallery \
https://svn.sourceforge.net/svnroot/gallery/branches/MY_DEVEL_BRANCH
you@yourbox:~/code> svn checkout https://svn.sourceforge.net/svnroot/gallery/branches/MY_DEVEL_BRANCH
you@yourbox:~/code>
Using svnmerge is simple and makes tracking your revisions easy. Before you start on your new branch, you can init svnmerge, which will start keeping track of changes. Now you're ready to make changes and commit back just like you're used to:
you@yourbox:~/code> cd MY_DEVEL_BRANCH you@yourbox:~/code/MY_DEVEL_BRANCH> svnmerge init you@yourbox:~/code/MY_DEVEL_BRANCH> ... make your changes in your branch... you@yourbox:~/code/MY_DEVEL_BRANCH> svn commit Committed revision 123. you@yourbox:~/code/MY_DEVEL_BRANCH>
Now it's time to merge your branch changes back into the trunk. There are a couple of methods to doing this. One (not shown here) is to merge only over the revisions to the trunk made since either your initial branch or since your last merge. This is simple enough if your branch has a short lifetime.
But more than likely, you'll want to keep your branch in sync with the trunk. You only want to merge your branch in over the revisions since the last merge you made. The svnmerge script helps out so you don't need to remember which versions need to be merged against. So first you want to bring your branch "in-sync" with the trunk:
you@yourbox:~/code/MY_DEVEL_BRANCH> svnmerge avail 94-117 you@yourbox:~/code/MY_DEVEL_BRANCH> svnmerge merge U file/changed/in/trunk.php C file/changed/in/trunk/and/your/branch/with/a/conflict.php you@yourbox:~/code/MY_DEVEL_BRANCH>
svn diff,
svn resolved[ ]
Uh oh so we have a conflict in one file which needs to be resolved. You can inspect the conflicts with svn diff. Then you can manually clean up the conflict in the file, and then resolve the file as fixed:
you@yourbox:~/code/MY_DEVEL_BRANCH> svn diff file/changed/in/trunk/and/your/branch/with/a/conflict.php needs more commentary here... you@yourbox:~/code/MY_DEVEL_BRANCH> svn resolved file/changed/in/trunk/and/your/branch/with/a/conflict.php you@yourbox:~/code/MY_DEVEL_BRANCH> svn commit Sending file/changed/in/trunk.php Sending file/changed/in/trunk/and/your/branch/with/a/conflict.php Transmitting file data ... Committed revision 118. you@yourbox:~/code/MY_DEVEL_BRANCH>
svn merge (managed by svnmerge)[ ]
Now that your branch is "in-sync" with the trunk, it's time to merge your branch back into the trunk and commit the new changes. First you want to go back to your local trunk copy.
you@yourbox:~/code/MY_DEVEL_BRANCH> cd ../my_gallery_trunk_directory you@yourbox:~/code/my_gallery_trunk_directory> svn update At revision 118.
Since you know your branch is also up-to-date with that version, you can simply merge the branch to the head at the same revision.
you@yourbox:~/code/my_gallery_trunk_directory> svn merge https://svn.sourceforge.net/svnroot/gallery/trunk/gallery@118 \
https://svn.sourceforge.net/svnroot/gallery/branches/MY_DEVEL_BRANCH@118
U albums.php
U classes/AlbumDB.php
you@yourbox:~/code/my_gallery_trunk_directory> svn status
M albums.php
M classes/AlbumDB.php
you@yourbox:~/code/my_gallery_trunk_directory> svn commit
Sending albums.php
Sending classes/AlbumDB.php
Transmitting file data ...
Committed revision 119.
you@yourbox:~/code/my_gallery_trunk_directory>
As we approach the endgame of a release, we will fork off a new branch for that release (e.g. BRANCH_1_3_4 for Gallery 1, or BRANCH_GR_1_1 for Gallery Remote). At this time, the trunk will roll forward to the new release number (e.g. 1.3.5-cvs-b1) and you're free to commit as usual to the trunk. Changes to the release branch are restricted and are under control of the team lead in charge of the release. The correct strategy is to commit changes to the trunk, and only when directed by the release team lead can you merge your changes into the release branch. This gives us a reliable, predictable path to the release where we can control which fixes go in and which ones don't.
When a final release ships, the person leading the release will tag the module so that particular release can easily be reconstructed from the Subversion repository. The naming convention for these tags is RELEASE_1_3_4 for Gallery 1 (RELEASE_GR_1_1 for Gallery Remote). In Subversion, the method for syncing to a tag is identical to syncing of a branch. Each tag has its own directory (under the tags/ directory, just like branches living under branches/), the only difference from a branch being that tags do not receive updates via commits.
Unit Testing Guidelines[ ]
When doing development work on Gallery 1.x, you should do the followoing tests on any new code before submitting it to us as a patch. This will help to weed out simple mistakes.
- Rename albums and photos
- Change the order of albums and photos
- Edit captions, titles, descriptions, and photo properties
- Move photos and albums:
- To the top level, then back again
- To another album within the same album hierarchy
- To another album in a different album hierarchy
- Combinations of the above, while also setting highlights before the move, and verifying that it gets reset after the move
- Mass editing of album properties (i.e. apply settings to nested albums)
- Deletion of albums
- Hiding and un-hiding albums and photos, with and without moves involved
- Modifying album permissions
- Mass resizing and thumbnail rebuilding
- Adding new photos to existing albums
- Creating new nested albums, then adding photos to them
- Adding new top-level albums, then adding photos to them
You can skip some of these tests if you're absolutely sure that your code doesn't affect them. But they're going to have to get tested one way or another, so you might as well do them sooner rather than later. Thanks to vallimar for the list!