Adding/renaming/removing files - Developer documentation - Coppermine Photo Gallery - Documentation & Manual

# Coppermine Photo Gallery v1.5.x: Documentation and Manual

# Adding/renaming/removing files

## Target audience

This part of the documentation is not meant for end users of Coppermine, but only for developers. There is no support for this section, it comes as-is.

## Scope

This document is meant to explain what needs to be done by developers when adding / renaming / deleting files to/from the SVN during development stage.

## Naming conventions

Refer to the section "Naming Conventions" when adding new files or renaming existing files.

## Adding files

If a developer needs to add a new file to Coppermine's core, here's a list of things that needs to be done:

- Create the file locally on your client (within the working copy of your Subversion checkout), respecting the naming conventions
- If it is a non-binary (i.e. a text file), add the file header that will show that your file is part of the coppermine package. Currently, the file header for PHP files looks like this:

      /*************************
        Coppermine Photo Gallery
        ************************
        Copyright (c) 2003-2012 Coppermine Dev Team
        v1.0 originally written by Gregory Demar

        This program is free software; you can redistribute it and/or modify
        it under the terms of the GNU General Public License version 3
        as published by the Free Software Foundation.

        ********************************************
        Coppermine version: 1.5.18
        $HeadURL$
        $Revision$
      **********************************************/

  For other file types (e.g. sql files), different comment symbols might apply.
- Add the file to the SVN, using the add and then the commit command of your favorite SVN client
- In your SVN client, make sure that the file you have added has the needed SVN-properties. In RapidSVN (Linux-Client), do a right-click, properties and make sure that the name/value pair "svn:keywords"/"Author Date Id Revision HeadURL" exists. If it doesn't exist, create such an entry (using the "new" button on the properties dialog). This will make sure that the placeholder SVN variables within $-signs are populated properly. Take a look at existing files to see how this is done.
- Add an entry for your newly-created file in `includes/cpg15x.files.xml`. Details can be found in the section Versioncheck : XML structure
- If applicable, come up with instructions about your file in the documentation

### Language files

Adding (user-contributed) language files to the package is a process that needs to be performed in various steps. Those steps don't necessarilly have to be performed by one single developer, but it's advisable that only one dev takes care of a language file contribution to make sure that everything works flawlessly.
This section is not aimed at end users who want to add a language file to Coppermine. Instead, this section is only aimed at members of the Coppermine developer team and nobody else than the team members. Please do not ask questions on the Coppermine support board that deal with the contents of this page, as they simply don't apply to you.

- In the channel where the language file has been contributed (usually in a posting on the forum where a user has attached the language file), reply and say that you as a dev team member are volunteering to add the file. This is meant to make sure that the effort is not taken twice.
- Download the file and unarchive it if needed into your testbed
- Start your testbed and force the usage of the new language file by adding the corresponding parameter to the browser's address bar. The testbed should appear in the chosen language. For a basic test it is enough to verify that the language file doesn't break the testbed with an error message or unexpected output.
- Edit the language file with a plain text editor and verify that the header is intact as suggested above. Pay attention to the Coppermine version number that often doesn't match in user-contributed language files.
- Populate the array `$lang_translation_info` if the translator hasn't done so already. If the translator hasn't supplied a website that he wants to be refered to in the credits section of the docs, refer to the user's profile page of the forum instead.
- Verify that the language file is in unicode (UTF-8 without a BOM) if you can.
- Edit the translator credits of the documentation. In an ideal world you'd be editing all credits files for all documentation languages (`docs/language_name/credits.htm` and add the credits for the translator there, but of course this get's increasingly harder with a growing number of documentation languages. Therefore, it's acceptable if you just edit the English section of the documentation (`docs/en/credits.htm`) accordingly and leave the rest to the maintainers of the individual documentation localizations.
- As with all files, you need to edit `includes/cpg15x.files.xml` as well to reflect the newly added file there.
- Next you need to figure out the status of completion of the language file contribution, i.e. if it's a full translation or only a partial translation. This is a very hard task that might not yield perfect results, so when in doubt, flag a translation as partial translation, which doesn't have an impact in a technical sense, but only serves as an information for end users.
  Factors to help you determine if a language file is a full translation or a partial translation can be:
  - The contributor may have posted in his forum posting wether his translation has been done partly or fully.
  - File size: file sizes for full translations can differ dramatically (as languages that have symbols for words or syllables are less space-consuming than languages that are composed of letters that represent sounds (phonemes to be exact). But with the English language file having roughly 180 KB it's pretty obvious that the language file for British English (`lang/english_gb.php`) can not be a full translation, but only a partial translation (which is not very surprising, as it contains only the strings where British English differs from American English)
  - Cursory reading through the language file in your plain text editor should give you an idea if much of the original, underlying English text shines through, espcially when looking at a language file that is using another character set than latin.
- You will need to make sure that the translation table in Coppermine's database table structure get's updated as well both for fresh installs as well as for updates, that's why you need to
  - edit `sql/basic.sql`, find the lines that start with `INSERT INTO CPG_languages` and make sure that the language you're adding exists and that the level of completion of the language file matches the database record.
    If you're about to add a Klingon language file, search the content of `sql/basic.sql` for the string `klingon`. If it's there, i.e. if a line like
    INSERT INTO CPG_languages (lang_id, english_name, native_name, flag, abbr, available, enabled, complete) VALUES ('klingon', 'Klingon','tlhIngan','klingon','', 'NO', 'NO', 'NO');exists, just edit the fields that determine if the translation exists and wether it's complete (full translation) or not.
    If a line that corresponds to the new language's English name doesn't exist, create it (keep the alphabetical structure of the `INSERT INTO CPG_languages`-section in mind) accordingly.
    For details, refer to the language manager documentation.
  - edit `sql/update.sql` with a plain text editor.
    - If the line in `sql/basic.sql` that corresponds to the new language file didn't exist, you will need to add a line to `sql/update.sql` that adds a new record.
      For the above mentioned Klingon language file, the line to create a new database record would be INSERT INTO CPG_languages (lang_id, english_name, native_name, flag, abbr, available, enabled, complete) VALUES ('klingon', 'Klingon','tlhIngan','klingon','', 'YES', 'NO', 'NO');
    - If there has been a database record already for the language file and you just need to toggle it from unavailable to available, add a line that performs the update
      The example for Klingon in this case would be UPDATE CPG_languages SET `available` = 'YES' WHERE `lang_id`='klingon';
- Make sure that there is a flag image inside the folder `images/flags/` that represents the new language. If there is no flag available, create one if you have the skills to do so and add that file. Alternatively, assign a blank image as a flag as a temporary workaround.
- Add the new language file in your SVN client to the repository. You will need write access to the subversion repository in order to accomplish this.
- Add a line to the change log that corresponds to the new language file.
- Test the language file as thoroughly as you can on your local testbed: browse the gallery as guest, registered user and admin, try to upload a file, take a look at the main views (index, thumbnail page, intermediate image).
- Commit your changes to the subversion repository using your subversion client.
- Finally reply to the thread where the user has contributed the language file, posting that you have done what you did. It might help to add a reference to the web SVN and post the revision of your commit.
- If you have admin privileges on the Coppermine forum, change the language file contributor's group membership; make him member of the translator group.
- If you have access to the Coppermine internet site, edit the credits file there as well to reflect the newly added translator.

## Renaming files

If a file name can not be kept (e.g. because of collision with naming conventions), it should be renamed instead of deleting the old one and creating a new one. The benfit of renaming is the fact that the version history will be kept in the Subversion repository.

Once a file has been renamed in SVN, you will have to make additional edits:

- Add an entry for your the new file name in `includes/cpg15x.files.xml`. Details can be found in the section Versioncheck : XML structure
- If the old file name already has gone into a prvious public release, you need to make sure that end users will not have an outdated, leftover copy of the file with the old name when performing an update. To accomplish this, you should edit `update.php`, find the definition of the array `$delete_file_array` and add the old file name to it.
  Additionally, you should edit `includes/cpg15x.files.xml` and flag the old name with the status "remove".
- If the old file name has not gone into a previous release, it's enough to edit `includes/cpg15x.files.xml` and just remove the record that refers to the old file name.
- You have to search through all files (both PHP files as well as HTML files inside the documentation) for references to the old file name and change the references as well.

## Deleting files

In a nutshell: what has been said above about renaming files applies to deleting files as well: after having deleted the file in SVN, make sure to edit the XML file used for versioncheck and the array of files scheduled for deleting by the updater.

Keep in mind though that before deleting core PHP files, you should discuss this with your fellow devs first on the dev-only board.