编辑“Gallery1:Developer Guide”

== Coding Standards ==

Try as much as possible to follow the [[Gallery:Coding_Standards|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 [http://subversion.tigris.org/ Subversion] on the [http://sourceforge.net/ SourceForge] site to maintain software revisions. You should first spend some time reading over the [http://sourceforge.net/docman/display_doc.php?docid=31070&group_id=1 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 [http://svnbook.red-bean.com/nightly/en/svn.forcvs.html Subversion for CVS Users] appendix useful (from the O'Reilly ''[http://svnbook.red-bean.com/nightly/en/index.html Version Control with Subversion]'' book).

=== [http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.checkout.html 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 <nowiki>https://gallery.svn.sourceforge.net/svnroot/gallery/trunk/gallery</nowiki>

If you just want to keep up to date with the latest stable code:

 svn checkout <nowiki>https://gallery.svn.sourceforge.net/svnroot/gallery/branches/BRANCH_1_5_LEGACY/gallery</nowiki>

=== [http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.update.html 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 <tt>gallery/</tt> 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.

=== [http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.status.html svn status], <br>[http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.diff.html svn diff] ===

As you're editing, you can use <tt>svn status</tt> and <tt>svn diff</tt> to inspect which files you've modified and what the differences are.

=== [http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.commit.html 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 [[#Updating_the_ChangeLog_and_Version_Bumping | 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 <tt>ChangeLog</tt> 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 <tt>.emacs</tt> 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 <tt>ChangeLog</tt>, it needs to be changed in the <tt>Version.php</tt> file as well:

 $gallery->version = "1.3.4-cvs-b16";

If you've made a change in the Config. Wizard that requires the <tt>config.php</tt> 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 <code>integrityCheck()</code> 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 <code>include()</code> or <code>require()</code> call, you must add the file to the <code>$safe_to_include</code> array in <tt>index.php</tt>. 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 (<tt>-rw-r--r--</tt>), but directories and executable scripts should have 755 (e.g. <tt>drwx-r-xr-x</tt>) 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'''.

=== [http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.copy.html svn copy] ===

To familiarize yourself with Subversion branches properly, you should read the [http://svnbook.red-bean.com/nightly/en/svn.branchmerge.html Branching and Merging] chapter from the O'Reilly ''[http://svnbook.red-bean.com/nightly/en/index.html Version Control with Subversion]'' book. You might also be interested in the  <tt>[http://www.dellroad.org/svnmerge/index svnmerge]</tt>, a small Python script which can help to simplify the <tt>svn merge</tt> command for you. A typical Gallery branch example follows, using <tt>svnmerge</tt> 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 <nowiki>https://svn.sourceforge.net/svnroot/gallery/trunk/gallery</nowiki> \
                              <nowiki>https://svn.sourceforge.net/svnroot/gallery/branches/MY_DEVEL_BRANCH</nowiki>
 '''you@yourbox:~/code>''' svn checkout <nowiki>https://svn.sourceforge.net/svnroot/gallery/branches/MY_DEVEL_BRANCH</nowiki>
 '''you@yourbox:~/code>''' 

Using <tt>svnmerge</tt> is simple and makes tracking your revisions easy. Before you start on your new branch, you can '''init''' <tt>svnmerge</tt>, 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 <tt>svnmerge</tt> 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>''' 

=== [http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.diff.html svn diff], <br>[http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.resolved.html svn resolved] ===

Uh oh so we have a conflict in one file which needs to be resolved. You can inspect the conflicts with <tt>svn '''diff'''</tt>. 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>''' 

=== [http://svnbook.red-bean.com/nightly/en/svn.ref.svn.c.merge.html svn merge] (managed by [http://www.dellroad.org/svnmerge/index 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 <nowiki>https://svn.sourceforge.net/svnroot/gallery/trunk/gallery@118</nowiki> \
                                                          <nowiki>https://svn.sourceforge.net/svnroot/gallery/branches/MY_DEVEL_BRANCH@118</nowiki>
 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 <tt>tags/</tt> directory, just like branches living under <tt>branches</tt>/), 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 [http://gallery.menalto.com/user/563 vallimar] for the list!

[[Category:Gallery 1:Development|Developer Guide]]