Target audience

This part of the documentation is not meant for end users of Coppermine, but only for developers. There is absolutely no support for this section, it comes as-is. If you're not a member of the Coppermine dev team, then the contents of this page are not meant for you.

Subversion repository

In the first place you need to perform core actions on the subversion repository level of Coppermine. For this purpose, you need to have write access to the subversion repository, which is something you can not make up. A dev team member with project admin status needs to have granted you write access to the subversion repository that is hosted at sourceforge.net. You need to have some experience in using your subversion client before trying to accomplish the actions described here.

Steps

These steps need to be taken to package a new release.

• Check out

  As with all subversion operations, you need to perform a checkout to make sure that your working copy of the subversion repository is up-to-date.

• Edit the version number

  To edit the version number of the Coppermine release, you will need to edit several files:
  • The actual version number is being stored in the file include/init.inc.php, so you will need to edit that file with a plain text editor and find , where X corresponds to the current minor version count that needs to be counted up.
  • The version number output of all pages of the documentation is being replaced using the JavaScript file behind each localization folder; that's why you need to loop through all language folders within the docs-folder, edit script.js, find the definition for the function cpgDocHeader and inside that definition change the localization line that corresponds to , where X stands for the minor version number.

• Replace version number in all files

  You need to loop through all text files (file extensions .php, .css, .js, .txt, .sql, .htm) and replace the version number in the header with the version number of the new release.
  
  You will have to find and replace with
  To accomplish this, you will need a tool that can batch-replace in files:

  • Linux

    On most posix-compliant operating systems (like Unix, Linux, BSD etc.) you should have all needed tools at hand already. Basically you loop through all files with a given extension, search for the string inside it and replace it. The command that can be run in a console could look like this: find /path/on/filesystem/level/to/your/working/copy/ -maxdepth 4 -name "*.php" -o -name "*.css" -o -name "*.js" -o -name "*.txt" -o -name "*.sql" -o -name "*.htm" | xargs sed -i 's/Coppermine version: 1.5.X/Coppermine version: 1.5.Y/g' If you want to turn this into a shell script, don't forget the shebang at the start of the file (usually something like #!/bin/sh).

  • Windows

    On Windows-driven computers you will need an editor that is capable to replace in multiple files or a tool that is dedicated to the replacement of text in files like the freeware apps Replace in files by Emurasoft or the app MB-Search&Replace by Markus Bader. Both apps are available in English as well as in German and both don't require an installation (the executable runs out of the box, even from a USB stick or similar).
  After having looped through all files, check in your subversion client if you actually have changed all non-binary files inside the package - all files should be marked as "changed" in your subversion client. Those that are not marked as changed require manual editing - maybe the version number had been forgotten to be changed in the previous release or when the file was added to the subversion repository in the first place.
  Don't commit your changes yet though; there are some more edits that need to be performed.

• Remove Byte Order Marks

  As Coppermine is a community effort and there are many developers who have write access to the subversion repository it might happen that a Byte Order Mark (BOM) has crept into non-binary files. This happens without the developer being aware of it and shouldn't cause a lot of fuzz among the dev team, yet it can cause serious issues after the release, with the byte order mark shining through on some or all pages and especially with authentification issues, as the pre-mature start of the output (even if it's just the accidental output of the BOM) will interact with the browser's ability to receive the header and subsequently the cookie.
  That's the reason why it's a good idea to scan the non-binary files (file extensions .php, .css, .js, .txt, .sql, .htm) once more for the existance of a BOM and get rid of it if present. On Windows-driven computers, the BOM usually manifests with "funny" charcters - usually , so you should loop through all text-only files for that string and get rid of that string by replacing it with "" (nothing), using exactly the same tool used for the version number replacement above.

• Prepare an announcement thread

  Prepare an announcement thread in advance (before you actually release) inside the dev-only sub-board of the Coppermine forum. This thread can be empty - you can fill it later, or have another dev team member fill it. You need to create it in advance in order to be able to refer to the thread from within the documentation that will ship with the release.

• Edit the upgrade section of the docs

  Edit the upgrade section of the docs and (if you can) the other corresponding sections of the localizations of the docs. Find the table inside the section "Reasons for package releases" there and add a table row at the top with the needed information. Take a look at the other table rows that correspond to previous release to get an idea what should go into that section. Refer to the changelog file in the root folder to figure out about the changes that went into the release that you're about to package. Don't forget to refer to the announcement thread that you have created in the previous step to make sure you can inform users about last minute changes accordingly.

• Edit the changelog

  Add at least one line to the changelog that explains the version number change that you're about to commit. Add a line as well that mentions the release date.

• Commit your changes

  Of course you need to commit all your changes to the subversion repository, using your subversion client.

• Update the versioncheck data

  This is the most complicated step. It needs to be taken after having committed all other files to make sure that their revision numbers and hashes no longer are altered.
  Edit the file include/cpg15x.files.xml inside your working copy of the subverion repository with a plain text file.

  • Completeness

    In this step you need to make sure that the XML file is complete. Loop through the changelog to check if all files (language files etc.) that have been added to the subversion repository since the previous release have been added to include/cpg15x.files.xml file as well. If all developers have done as suggested, there should be nothing left to do for you in this aspect. Save your changes (if any).

  • Update revision numbers and hashes

    Coppermine is storing the checksums for each file to allow the user to check that a file hasn't been tampered with. In this step, the checksums (hashes) are being calculated.
    • Run the versioncheck utility in your browser with the parameter ?output=create as suggested in Versioncheck → Hidden features while being logged in as admin (the URL in your browser's address bar looking like this: http://yourtestbed.tld/your_coppermine_folder/versioncheck.php?output=create. The versioncheck tool will then loop through all files specified in include/cpg15x.files.xml and re-calculate the hashes and outputs them again in XML.
    • There should be a huge textarea field that contains everything you need - just select the entire field's content,
    • copy to clipboard,
    • go to your editor where you have include/cpg15x.files.xml opened previously,
    • highlight everything in the editor window and delete the content there.
    • Paste the content of the clipboard into the empty editor window that corresponds to include/cpg15x.files.xml.
    • Then remove whitespace (if any) after the closing </file_data>-tag
    • and finally save the changes in include/cpg15x.files.xml.
    • Go back to your browser window and remove the parameter ?output=create from the address bar. Make sure not to connect to the online repository by ticking the corresponding checkbox to make sure that you're looking at the changed file. In all the three columns "Version", "Revision" and "Modified" you should by now see green check icons that show everything is OK. There mustn't be any warnings in red. If this is the case, continue.
    • Commit your changes applied to include/cpg15x.files.xml to the subversion repository.

• Create a tag in subversion

  Create a tag using your svn application. The target directory name will be the abbreviation cpg followed by the exact version number. So the target URL will be https://svn.code.sf.net/p/coppermine/code/tags/cpg1.5.X, where X represents the minor version number that you're about to tag.

  • RapidSVN

    tbc

  • Tortoise SVN

    • In the left frame that represents the folder view, highlight the folder that represents the root of cpg1.5.x
    • Click on the menu entry "TortoiseSVN" - "Branch/tag..."
    • In the copy dialog, modify the "To URL" accordingly (see above).
    • Select "HEAD revision in the repository" as source and click on the "OK" button.

• Export from subversion

  By now it's time to create the actual package, so you may be tempted to just zip your local working copy of the subversion repository, but that would be a very bad idea, as both your individual config file as well as all your changes (e.g. test uploads etc.) would be residing in that copy. Additionally, a lot of garbage would reside in that copy, as subversion creates a lot of hidden files inside your local working copy.
  That's why you need to perform an export from the subversion repository into a new, empty folder on your client and use that from now on. This will make sure that only the files that are meant to go into the package will actually go into your package.
  How the export feature actually works depends on the subversion client you use. The list items below describe the process just for some example clients:

  • RapidSVN

    The subversion client RapidSVN is available for many platforms (Linux, Windows, Mac OS/X, Solaris, etc.) and in many languages (English, German, French, Italian, Portuguese, Russian, Ukrainian, Simplified Chinese, Japanese). The Coppermine dev team recommends it as graphical client on Linux-driven systems.
    • In the left frame that represents the folder view, highlight the folder that represents the root of cpg1.5.x
    • Click on the menu entry "Repository" - "Export..."
    • In the export dialog, make sure that as revision the "Use latest" checkbox is ticked and that the "Recursive" checkbox is ticked as well.
    • As Destination directory, you need to specify a folder name that doesn't already exist within a folder that does exist. This dialog is a little bit unusual, so here's a detailed example, assuming that you're on Linux and that your user name is johndoe:
      • On the export dialog, click on the button with the three dots within the "Destination Directory" section that allows you to browse the folder structure
      • In the sub-dialog that open, browse to the Desktop folder within your user's home folder, i.e. to /home/johndoe/Desktop and hit the "OK" button. This will close the sub-dialog and populate the input field "Destination Directory" in the export dialog with the absolute path you just selected.
      • Click into this input field to put your cursor into that field to the end (right after /home/johndoe/Desktop) and type a slash, followed by the name of the sub-folder that you want to get created, e.g. cpg15x. After you did that, the input field's content now should look similar to this: /home/johndoe/Desktop/cpg15x
      • After having verified that everything looks as expected, click on the "OK" button of the export dialog.

  • Tortoise SVN

    • In the left frame that represents the folder view, highlight the folder that represents the root of cpg1.5.x
    • Click on the menu entry "TortoiseSVN" - "Export..."
    • In the export dialog, make sure to uncheck "Export unversioned files too" and "Omit externals".
    • Select the destination directory and click on the "OK" button.

• Create the archive

  Create an archive according to the naming conventions, using your favorite archiver (on Windows, 7-Zip is recommended). The naming convention for package releases is pretty straightforward: it's just the abbreviation cpg followed by the exact version number. Subsequently, your archive should be named cpg1.5.X.zip, where X represents the minor version number that you're about to package. Its'mandatory to come up with a zip archive, but you can come up with additional archives as well (e.g. .7z, .tar.gz or .tar.bz2) to make things easier for users on alternative operating systems.

• Upload the archive

  The archive(s) created in the previous step are meant to go into the download repository at https://sourceforge.net/projects/coppermine/files/. You will need packager privileges on the Coppermine project pages that reside on the sourceforge.net webspace.
  • Log in into your account on sf.net
  • Go to the File Manager
  • Expand the folder labelled "Coppermine"
  • Expand the folder labelled "1.5.x"
  • Click the "Add File" button
  • Browse to your package on your client and select it for upload
  • After uploading has finished click on the "i" icon in the uploaded package's row and set it as default download for all operating systems

• Publish announcement thread

  Move the announcement thread from the dev-only board to the announcement board. You will need moderator capabilities on forum level.

• Update cpg15x.files.xml on the Coppermine home page

  The xml file that contains the information about the most recent stable release needs to be uploaded to the official web space, replacing the file http://coppermine-gallery.net/cpg15x.files.xml that clients will connect to when checking for upgrades with the one from the subversion repository (e.g. the file that corresponds to https://svn.code.sf.net/p/coppermine/code/trunk/cpg1.5.x/include/cpg15x.files.xml). If you don't have access to the project's official webspace by FTP, ask a fellow developer to perform this task for you.

• Update the download button on the Coppermine home page

  On our Coppermine home page you need to update the URL and title of the download link as well as updating the button image itself.

• Create news items

  There are various news items that need to be created. They can all be filled with similar or even identical content, as they catter for different media or different ways to access the news.

  • News item on sf.net

    Create a news article on sf.net that contains a link to the announcement thread. To accomplish this, select, "News" from the "Develop" menu while being logged in with your sourceforge.net account. On the news page, use the "Submit" link to create a news item. The news item should contain a link to the announcement thread on the forum.

  • News item on forum

    Create a news item on the forum that contains a link to the announcement thread. You will need the corresponding priviledge on the forum.

  • News item on home page

    On the Coppermine home page, create a news item that contains a link to the announcement thread. Move outdated news items to the news archive.

  • News embedded into existing galleries

    To make users of existing galleries aware of the new release, edit http://coppermine-gallery.net/cpg15x_news.htm. This file is the source for the news item that is displayed for Coppermine admins on their galleries if the option Display news from Coppermine-gallery.net is enabled.

• Update the demo

  Use your favorite FTP app to update the demo on the Coppermine home page. You will of course need FTP access to the corresponding web space.
  Make sure not to overwrite the custom anycontent.
  Keep in mind that you need to apply changes to the JavaScript file script.js inside the localizations of the docs folder - they compose the site navigation.