Joomla! 1.5 Development Cookbook

By James Kennard
  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Development using JoomlaCode.org and SVN

About this book

Joomla! is the world's hottest open-source content management system. Out of the box, Joomla! does a great job of managing the content needed to make your website sing. Many Joomla! developers face common implementation hurdles, some might want to rapidly extend the Joomla! core functionality or might want to create new and exciting extensions.

This book has a "wealth" of solutions for problems that Joomla! developers face regularly. It provides step-by-step mini examples which show how to overcome common design and implementation problems when creating Joomla! extensions. It will help you setup a sustainable collaborative development environment using the powerful free services offered by JoomlaCode.org.

This book can be used in different ways. It can be used by the pro Joomla! developer looking for a specific solution to a problem and can also be used by a novice developer looking for an insight into an area of common problems, such as effectively handling errors in Joomla! Readers who choose to read an entire chapter will first be given a brief overview of the topic in hand and its role and importance when developing for Joomla! The Recipes contained within the chapter will introduce the reader to specific problems and provide hands-on solutions. It provides solutions for core design topics including security, data access, users, sessions, and multilingual capabilities.

Publication date:
September 2009
Publisher
Packt
Pages
360
ISBN
9781847198143

 

Chapter 1. Development using JoomlaCode.org and SVN

This chapter contains the following recipes:

  • Setting up a JoomlaCode.org project

  • Managing members of a JoomlaCode.org project

  • Setting up JoomlaCode.org Subversion

  • Understanding the Subversion skeleton

  • Understanding revisions in Subversion

  • Understanding the Subversion process

  • Checking out a Subversion repository using TortoiseSVN

  • Editing a working copy using TortoiseSVN

  • Inspecting changes using TortoiseSVN

  • Updating a working copy and resolving conflicts using TortoiseSVN

  • Committing changes using TortoiseSVN

  • Exporting a working copy using TortoiseSVN

 

Introduction


In this chapter, we investigate how we can utilize the free JoomlaCode.org project hosting service. In particular, this chapter addresses how to use JoomlaCode.org SVN (Subversion) and how to work with SVN using the popular visual TortoiseSVN client for Windows.

JoomlaCode.org ( http://www.joomlacode.org ) provides a project management solution for open source Joomla! projects. The following list describes the tools that JoomlaCode.org provides us with:

  • Document Manager: Simple document publishing (usually documentation)

  • File Release System (FRS ): Packages released by the project

  • Mailing Lists: Multiple mailing list manager

  • News: Latest project news

  • Public Forums: Discussion forums for JoomlaCode.org users

  • Public Wiki: Collaborative online documentation

  • Source Control Management (SCM): Manage code base using CVS, SVN, or Git (in this book we focus on SVN exclusively)

  • Tracker: Manager for tracking feature requests, bugs, and patches

The following diagram shows how these various tools can be thought of when used together. Note that this is not a concrete representation; how we utilize the tools that JoomlaCode.org provides us with is always the overriding factor.

Tip

Don't let the tools dictate the processes

Software development isn't just about the tools we use. It is about the processes we undertake. We should use the tools that best fit our processes, as opposed to using the processes that happen to fit our tools.

Before we continue, we should take time to note that not all projects will successfully qualify for JoomlaCode.org project space. JoomlaCode.org only supports non-commercial open source Joomla! projects. Remember that non-commercial and open source are not mutually exclusive; it is possible to commercially release an open source product. If we are not creating a non-commercial open source project, there are other similar free and paid-for services; the following table compares four popular alternatives:

 

Assembla (1)

Google Code

SourceForge (7)

Unfuddle

Free Project Hosting

YES

YES

YES

YES

Commercial Project Hosting

YES

NO

NO

YES

Closed Source Project Hosting

YES

NO

NO

YES

Public Forums

YES (2)

YES (4)

YES

NO

SCM

Subversion, Git, Mercurial

Subversion

Subversion

Subversion, Git

Tracker

YES

YES

YES

YES

Document Manager

YES

YES (5)

YES (8)

NO (9)

News

YES (3)

YES (6)

YES

NO

FRS

NO

YES (5)

YES

NO

Mailing Lists

YES

YES (4)

YES

NO

Public Wiki

YES

YES

YES

NO (10)

  1. Assembla intends to add a package to their catalog, specifically for Joomla! projects. This package will enable an enterprise-level commit-stage-release cycle in the development process. Assembla also provides an unusually high level of integration with other services; for example, we could hook into a JoomlaCode.org Subversion repository.

  2. Assembla Messages Tool can be used to this effect.

  3. Assembla does not offer a News tab. However, Assembla will display a stream of all project activity, and a Messages tab.

  4. Google Code integrates with Google Groups. Google Groups provides public forums and mailing lists.

  5. Google Code provides downloads which can be used as an FRS and Document Manager.

  6. Google Code integrates with Blogger, and a blog can be used to this effect.

  7. SourceForge is very similar to JoomlaCode.org (the underlying systems are much the same, GForge, used by JoomlaCode.org, is a fork of the SourceForge system).

  8. SourceForge Documentation Plugin can be used to this effect.

  9. Unfuddle does not specifically provide a Document Manager, but files can be attached to tickets, messages, and notebooks.

  10. Unfuddle does not provide a public wiki, but does provide notebooks that can be used like a private wiki.

    Note

    SVN is an SCM tool, and SCM is part of SCM… Confusing, isn't it! Let's try that again: Subversion is a Source Control Management tool, Source Control Management is part of Software Configuration Management. Which just goes to show the computer industry really does love its acronyms just a little too much! Even the IETF likes to have some fun with this once in a while http://tools.ietf.org/html/rfc5513.

JoomlaCode.org can be thought of as a system that provides Software Configuration Management. And as part of that package, we get Source Control Management tools. The topic of Software Configuration Management is beyond the scope of this book, and we will not be discussing it further.

Source Control Management is an integral part of modern software development. We need Source Control Management in our projects because it:

  • Allows concurrent collaborative development of source code (working copies)

  • Tracks all changes made to the source code (revisions)

  • Provides states to which we can return at any time (revisions)

  • Allows parallel development of various functionality (branches)

  • Can be used to manage releases (tags)

  • Can be used to maintain older versions (releases)

  • Provides a common vocabulary for discussing Source Control Management

Source Control Management does require a good level of understanding if it is to be used effectively. This book covers the basic usage and theory of using Subversion.

Tip

Subversion client freedom

Although in this book we work exclusively with the popular TortoiseSVN visual Windows Subversion client, it is possible to use several clients on the same working copy. Therefore, we do not need to worry about restricting ourselves to a specific client. For example, I use TortoiseSVN, CollabNet's command line client, and the Netbeans SVN plugin, dependant on what I am doing.

 

Setting up a JoomlaCode.org project


This recipe describes how to set up our own JoomlaCode.org project so that we can start developing and managing our new extension. Use of JoomlaCode.org is not compulsory.

Getting ready

To set up a JoomlaCode.org project we must create a JoomlaCode.org user account. To register for a JoomlaCode.org user account, all we need to do is follow the Register new account link displayed in the top-right corner of the JoomlaCode.org web site.

Note

The username we choose will be used for all activities that we initiate with JoomlaCode.org, for example using a JoomlaCode.org SVN repository.

Tip

JoomlaCode.org usernames must be lowercase. If you request a username with uppercase characters, these will be automatically replaced with the lowercase equivalent.

How to do it...

To create a new project we navigate to the My Stuff tab at the top of the page. This presents us with all sorts of information about our account. From the menu items on the lefthand side, select the My Account item. In the expanded menu there is an option to Register Project, shown as follows:

Once we select Register Project, we are presented with a form that allows us to define our project. The following table describes the purpose of the fields:

Field

Description

Project Full Name

Complete name of the project. This will generally be the name of the extension that we want to develop using JoomlaCode.org.

Project Purpose

What the project will be used for. This information is used exclusively to determine if the project should be approved for inclusion on JoomlaCode.org.

Project Public Description

Description of the project that is publicly viewable and searchable. This description is shown on the project home page and in the project listings. When a JoomlaCode.org user searches for a project, both the project name and description are searched.

Project UNIX Name

Restricted to alphanumeric characters, this field is used to uniquely identify the project. It is important to select a good UNIX name because the UNIX name of a project can never be altered. The UNIX name is used to identify the project home page, define the file repository location, and to access the GForge shell.

The UNIX name must have the following properties:

  • Unique to JoomlaCode.org

  • Contain between 3 and 15 characters

  • Contain only lowercase characters

  • Contain only characters, numbers, and dashes

Homepage URL

If as part of the project we also maintain a web site external to JoomlaCode.org, we can specify this here.

Template Project

Template to use as a basis for the new project. Selecting Empty Project provides us with a clean slate.

Trove Categorization: Development Status

Maturity of the project. When creating a new project it is likely that the project will be in the early stages of development, for example, Planning or Alpha.

Trove Categorization: License

The License under which the project is released. Remember that JoomlaCode.org hosting is only available for open source projects.

Trove Categorization: Programming Language

The primary programming language in which the project is written. The majority of projects are PHP and at the time of writing 86% of JoomlaCode.org projects are defined as PHP projects.

Trove Categorization: Topic

The topic that best describes the project. The topics are organized in a way similar to JED. This is really intended to allow users to browse through the JoomlaCode.org projects. However, most users prefer to use JED because it is more complete and provides a greater level of feedback from users of extensions.

Trove Categorization: Intended Audience

The type of user for whom the project is intended to provide services. For example, a project that provides code libraries would be considered to be intended for developers, where as a project that generates tag clouds would be considered intended for end users.

After submitting the registration form the project is ready for approval by the JoomlaCode.org team. The approval process is administered manually, and so it may take some time before the project is approved. If there are any problems with the approval of the project, we will be contacted and given the opportunity to further explain the project.

Once the project has been approved, an approval confirmation email will be sent to us. The following screenshot shows the email received for the project My JoomlaCode.org Project, UNIX name example-project.

We should now have a project ready to go! It is generally a good idea to edit the project home page at this stage. To do this, press the Edit project's homepage button displayed on the home page itself.

There's more...

Jo omlaCode.org projects are based on plugins. Each plugin provides us with a specific piece of functionality. When we look at the admin page for the project we find a list of plugins that we can enable and disable.

Note

It is generally best to enable each plugin as and when we require it. Projects that enable all plugins but do not actually make use of them can be frustrating for users who are trying to find information about the project.

Tip

Getting Help

Joo mlaCode.org uses GForge, and so the GForge documentation can prove helpful. Refer to http://gforge.org/projects/gforge/ for more information.

See also

The following two recipes explain how to manage members of JoomlaCode.org projects and how to set up a JoomlaCode.org SVN repository.

 

Managing members of a JoomlaCode.org project


This recipe explains how, as an administrator of a JoomlaCode.org project, we can manage members of a project. The members are the JoomlaCode.org users who contribute to a project. The nature of the contributions does not necessarily have to be code development. For example, a member may contribute by regularly answering questions on the project forum and contributing to the project Wiki.

Ho w to do it...

We manage members of our project using the Admin Options displayed to the righthand side of the project admin page.

To add a new member, select the Manage Members and Roles option. On this page, we will see a list of users who are already members of the project and their role in the project. At the bottom of this list is an option to add a new member. In the example shown as follows, we are attempting to add the JoomlaCode.org user webamoeba to the project with the Role of Admin.

Once we're all done, the new user will appear in the members list.

How it works...

Members of a project are always assigned a role. Roles define what a member can and cannot do. By default there is a single role, Admin. Allocating this role provides members of the project full administrative access to the project. Generally speaking, there should be only one or two members to whom this role is applied.

We can define additional roles and we can edit existing roles using the Edit Roles option in the Admin Options box. It is only possible to change permissions for plugins that are enabled in the project.

There's more...

In addition to manually specifying JoomlaCode.org users that we want to add as project members, users can request to join projects. Users can do so by pressing the Request to join project button displayed on the project home page and entering a short description of why they want to join the project. It is then up to us as a project administrator to accept or decline their request. To do this we use the Browse Project Join Requests link in the Admin Options box.

Tip

Only allow users you trust

It is not uncommon to receive requests to join a project by users who have misunderstood the meaning of member. Before allowing any user to join one of our projects, we should confirm exactly why they want to join and if we actually want them to!

 

Setting up JoomlaCode.org Subversion


This recipe describes how to set up Subversion for a JoomlaCode.org project.

Tip

SVN is not just for collaborative development

If we are the only developer for our project, Subversion can still be of use. Versioning, tagging, and branching are all invaluable functions irrespective of the number of developers.

How to do it...

Firstly we need to log in to our JoomlaCode.org project. From here we navigate to the Admin page. The Plugin Admin box displays the plugins that are active for our project; by default, none of the plugins will be activated. In the area named scm, change the radio button selection from None, to SVN repository. Once we submit our changes, SVN and SVN Admin will appear in the lefthand menu, as shown in the following screenshot:

There is delay between enabling Subversion and the repository becoming active. As soon as the repository is active, we can start using and browsing it!

How it works...

When we create a Subversion repository, the repository will be populated with a skeleton structure. The following screenshot shows us what our new repository should look like:

Note

This initial repository skeleton conforms to the suggested way of working with Subversion. The next recipe explains this skeleton in more detail.

As we can see, there is a normal looking filesystem tree structure, each item in the tree is of a specified revision and age. The last log entry shows the message that was created when the identified revision was committed; in this case, it is Initial Repository Skeleton.

See also

For information about setting up a project on JoomlaCode.org, please refer to the previous recipe Setting up a JoomlaCode.org project.

In the next recipe, Understanding the Subversion skeleton, we investigate the purpose of the skeleton folders that are initially created in the repository.

 

Understanding the Subversion skeleton


This recipe explains the purpose of the initial skeleton folders that are created in a new JoomlaCode.org Subversion repository.

How to do it...

Understanding the skeleton is vital when setting up a new repository. Getting it wrong early on in the set up process can lead to major problems later. There are three folders, each with a specific purpose. The following diagram describes the skeleton structure:

The folder that we will use the most is the trunk folder. This folder is the basis for all of current mainstream development activity. This is where the next release of the software will be developed.

The bran c hes folder is similar; current development activity also occurs here. However, it is not for mainstream development, it is used for parallel development. Parallel development is development that is taking place at the same moment in time but is pursuing a different goal. For example, if part of the developer team is working on a new area of functionality, to shield that line of development from the mainstream development—and vice versa—a new branch may be created specifically for that line of development.

It is important to understand that branches are nearly always reincorporated with the trunk at a later date. A new folder is created in the branches folder for every line of parallel development.

The concept of the tags folder in Subversion isn't much different from tagging in the semantic web. Tagging is all about semantics, giving things meaning. We create a new tag whenever we create a new release. Tags are always static, that is to say, no more development ever occurs to a tag.

So if there is no development, what's the point? A release will always be associated with a repository revision. For example, if we released our software at version 1.0.0 when the repository was at revision number 165, we could simply extract revision 165 at a later date to rebuild version 1.0.0. But 165 can hardly be considered an easy to remember number. Also, it does not bear any direct relation to version 1.0.0. Creating a tag that contains a complete instance of version 1.0.0 makes it semantically easy to understand, for developers and non-developers alike.

How it works...

OK, let's consider a really basic repository. This project has only one file, myonlyfile.php. There are two releases 1.0.0 and 1.0.1, and the developers are currently working on version 1.0.2. One of the developers is in the process of adding ACL support, and they are doing this separately from the main thrust of development. The following figure shows what the repository will look like:

Tip

Sticking to tradition

We do not have to work to these standards, and we can remove the skeleton structure if we do not want to use it. Generally speaking, it is best to stick to this arrangement, or a similar structure, because developers who are familiar with Subversion will be able to understand the repository structure immediately.

There's more...

Another useful folder we can add to the skeleton is the releases folder. The purpose of a releases folder is to enable release maintenance, after earlier releases have been surpassed by a newer release.

For example, if after we have released version 2.0.0 and if 20% of our user base is still using version 1.n.n, we may want to continue to resolve bugs in the earlier release. To manage this, we create a folder for each major release, which has been surpassed, in a releases folder. We can then continue to patch these versions without interfering with the main development.

The Joomla! project itself uses this approach. At the time of writing, in the Joomla SVN there is a releases folder that contains 1.0 and 1.5. Allowing continued maintenance of these versions whilst with the main development of 1.6 is addressed in the trunk folder.

 

Understanding revisions in Subversion


Part of what makes Subversion so useful is its ability to archive changes. This recipe looks at revisions and how they work in practice in a Subversion repository.

How to do it...

Revisions are expressed as a positive integer. Whenever a set of changes is committed to a repository, a new revision is created. The revision number is incremented every time changes are applied to the repository.

The revision number is global to the repository. In other words, it applies to all files, irrespective of which have been modified. The repository is always accessible as a whole at any given revision. For example, like pages in a book, when a new edition of a book is released all pages are of that edition.

The most recent revision is called the HEAD revision.

The following image illustrates how revisions and the skeleton described in the previous recipe correspond. Each circle represents a revision of the repository. The arrows represent the sources of the new revisions.

We can see that the trunk is continuously developed. We can see a branch created at revision 3 and reincorporated at revision 11. We can see two tags created at revisions 7 and 13 and that these are not modified after they have been created.

There's more...

Notice how the two tags are named 1.0.0 and 1.0.1. Revisions are a very technical (or if you prefer, nerdy or geeky or techie) way of referring to versions. Our tags have version names that are far easier to understand.

There is a standard form of versioning used by most software projects, which can be summarized as major.minor.patch. The impact of the changes dictates whether it is a major, minor, or patch update. For example, removing a bug would be a patch update, improving all of the views in a component would be considered a minor update, while adding some important extra functionality might be considered a major update.

Therefore, we can assert from our example that the changes made between version 1.0.0 and version 1.0.1 were a patch. Had we been using the revision number, we would not have been able to make any assertions.

See also

For information about setting up a project on JoomlaCode.org, please refer to first recipe in this chapter Setting up a JoomlaCode.org project.

In the next recipe, Understanding the SVN process, we will examine the theory behind the working practices of SVN.

 

Understanding the Subversion process


This recipe explains as a developer how to work with Subversion on a day-to-day basis.

Note

This recipe purposefully avoids referring to concrete examples. This recipe does, however, refer to Subversion commands, Subversion commands remain the same irrespective of the client.

How to do it...

When we work with Subversion we need a working copy. A working copy is an editable copy of all or part of the repository that is held on a client machine.

A working copy contains hidden metadata which is located in the hidden .svn folders. This metadata enables a Subversion client to understand the status of the working copy and to communicate with the server from which the working copy originated.

We obtain a working copy by checking out all or part of the repository. It is possible to check out any revision of the repository. In most instances we check the contents of the trunk folder and the HEAD revision (latest and greatest!).

Every working copy has a BASE revision. This is the revision that forms the basis of the working copy. In time we will find it necessary to update the BASE revision of our working copy.

As soon as we have a working copy we can start the iterative process of development!

Checking out is a one-off event used to obtain an initial working copy. The following diagram illustrates the iterative nature of working with Subversion once we have a working copy. We start in the Edit Working Copy position, and make our way around the circle until we end up back where we started.

The following list describes each segment of the circle:

  • Edit Working Copy

    • Add new files and folders (svn add)

    • Copy existing files and folders (svn copy)

    • Move/Rename existing files and folders (svn move)

    • Remove existing files and folders (svn delete)

  • Inspect Changes (1)

    • Compare working copy with the repository (svn diff)

  • Update Working Copy From Repository

    • Check for new revisions after the local working copy was last updated/checked out (svn status)

    • Get the latest updates from the repository and merge them with the working copy (svn update)

  • Test And Resolve Conflicts

    • Resolve conflicts introduced during the update (svn resolve)

    • Test the working copy to ensure that the update has not "broken" anything

    • Edit the working copy if changes made during the update require it

  • Inspect Changes (2)

    • Compare working copy with the repository (svn diff)

  • Commit Changes (create a new revision in the repository)

    • Apply the changes in the working copy to the repository (svn commit)

    Tip

    Commit only when ready

    As a general rule of thumb, we should only try to commit changes to an SVN repository once we have finished making a contained definable set of changes.

    Tip

    Leave a digital paper trail

    When we commit changes to the repository, we should always include a short concise message that describes the changes made. Doing so will pay dividends later should we need to inspect past changes.

    Note

    The process is likely to differ in practice. For example, we may update our working copy several times and resolve conflicts several times before we come to commit any changes.

How it works...

Subversion uses the Copy-Edit-Merge paradigm to enable several developers to edit the same files at the same time. Unlike traditional file sharing, the Copy-Edit-Merge paradigm removes the risk of one user irrecoverably overwriting changes made by another user. This is achieved by forcing users to resolve conflicts between their own changes and other users' changes before they are allowed to write their changes back to the repository. And, of course, the repository maintains an archive of past revisions, so we can always step back over the changes made.

We can visualize the state of the repository and the working copies, as shown in the following illustration. Here we can see the Subversion server connected to the Internet. In this instance, there are three users, all with working copies. User One has checked out a branch named ACL. User Two and User Three have checked out the trunk. The base revisions are 10, 14, and 11 respectively.

Note

Subversion servers do not keep a record of the various working copies. This means it is the responsibility of the developer to manage their working copy.

Tip

Locking in SVN

Subversion also supports the Lock-Edit-Release paradigm. This can sometimes be useful if we want to ensure that only one developer is editing a file at any one time.

There's more...

Subversion is an incredibly complex system. It is easy for new users of Subversion to underestimate its complexity, and as a result fail to maintain a repository correctly. The topic is far too big to cover in its entirety in this book. For more information, visit the official Subversion web site http://subversion.tigris.org/.

See also

To find out how to set up an SVN repository, refer to the recipe, Setting up JoomlaCode.org SVN. For information about applying the process described in this recipe, refer to all of the remaining recipes in this chapter.

 

Checking out a Subversion repository using TortoiseSVN


This recipe d escribes how to check out a Subversion repository using TortoiseSVN.

Getting ready

The first ste p we need to take is to download the latest version of TortoiseSVN and install it on our local Windows machine http://tortoisesvn.net/downloads/. TortoiseSVN is only available as an MSI (Windows Installer). TortoiseSVN installation requires a reboot after installation.

How to do it...

To create a new working copy we use the context menu on the folder in which we want to create the working copy. This menu will provide us with the SVN Checkout option for the My Working Copy folder, as shown in the following screenshot:

Selecting SVN Checkout prompts us with a dialog box; the following table describes the options in the dialog box:

Option

Description

URL of repository

Location of the repository, for JoomlaCode.org projects this is in the form http://joomlacode.org/svn/project-unix-name/sub/location, in most instances the optional sub location will be the trunk folder.

Checkout directory

Local directory into which we are checking out; this is automatically populated.

Checkout Depth

How much of the repository we want to check out. Generally this will be fully recursive, that is, all sub folders and files.

Omit externals

Also check out external repositories with which this repository links.

Revision

Revision of the repository to check out.

When we press the OK button, TortoiseSVN connects to the Subversion server and prompts for our JoomlaCode.org user credentials. It is possible to checkout anonymously; for this we enter the username anonymous, and leave the password field blank. The checkout process will then begin.

The transcript describes the actions taken during the checkout. This will generally take quite some time, depending on the size of repository. We can see from the transcript above that a total of one file was added to the working copy.

We now have a working copy ready and waiting!

There's more...

If we browse to our working copy, we will find the folders and files from the repository. At this stage all of these will be highlighted with a green-colored tick mark. This means that the file is part of the working copy and it is up-to-date. The following image shows the various icon overlays used by TortoiseSVN to indicate the status of files and folders in a working copy. Exact icons may vary.

The status of folders is often inherited from a subfile or subfolder. For example, if a conflicted file exists deep in the tree, parent folders will be highlighted as conflicted. This makes it very easy to locate problems in the repository.

Tip

Hey! Teacher! Leave them .svn folders alone!

We should never make changes to the hidden .svn folders. These folders contain the metadata required by Subversion clients. If we do experience problems with a working copy, we should use cleanup, as explained in the Committing changes using TortoiseSVN recipe later in this chapter.

See also

For an explanation of the role of checkout refer to the Understanding the Subversion process recipe, earlier in this chapter.

 

Editing a working copy using TortoiseSVN


This recipe describes how we make changes to a working copy.

Getting ready

All you right-handers out there need to warm up your middle finger on your right hand. All you lefties need to warm up your middle finger on your left hand. The context menu in Explorer is about to become your new best friend!

Ho w to do it...

As soon as we have a working copy, we can begin editing a repository. Editing existing files is the most common action. We don't need to do anything special in order to do this; just pick your favorite IDE/editor and work normally.

Adding new files and folders is just as easy; we simply create them as we would normally. However, because it is possible for a working copy to contain unversioned files—files that are not part of the repository—we must inform TortoiseSVN about new files and folders.

To do this, we can do one of two things. We can tell TortoiseSVN before we come to commit the changes by using the context menu TortoieSVN | Add command. Alternatively, we can select unversioned files and folders when we come to commit our changes.

Deleting is achieved slightly differently to normal. We delete files and folders using the TortoiseSVN | Delete context menu command. If we delete files and folders in the normal way, when we update our working copy, the removed files and folders will be restored!

Renaming should always be done using the TortoiseSVN | Rename command. If we do not use this, TortoiseSVN will misinterpret a renaming as a deletion of the original file or folder, and the creation of a new file or folder.

Mov ing files and folders is achieved using the TortoiseSVN | Relocate command. When we move files or folders, we can only move them to a folder that is versioned. That is to say, the new parent location in the tree must already exist in the repository. We can, alternatively, drag the file or folder using the mouse context button to the new location. Doing this provides us with a number of options, which are as follows:

  • SVN Move versioned files here : Moves to new location

  • SVN Move and rename version files here : Moves to new location and prompts for a new name

  • SVN Copy versioned files here : Copies to the new location

  • SVN Copy and rename versioned file here : Copies to the new location and prompts for a new name

See also

For an explanation of the role of editing a working copy, refer to the Understanding the SVN process recipe, earlier in this chapter.

 

Inspecting changes using TortoiseSVN


This recipe explains how to inspect changes made to files in a working copy using the TortoiseSVN tool TortoiseMerge.

How to do it...

Imagine we want to document language strings introduced in our working copy. To do this, we would use the context menu TortoiseSVN | Diff command. This allows us to compare our working copy with the base revision. In the example shown in the following screenshot, we can see that the new language string BAR has been added.

We c an obtain a status list of files and folders using the context menu TortoiseSVN | Check for modifications command. This tool provides us with two useful options—view a list of changes between our working copy and the base revision; and view a list of changes between our working copy and the HEAD revision.

Tip

The ability to inspect changes can be especially useful if we are attempting to track down a bug. For example, if it is known that a bug was introduced in revision 70, we can compare revision 70 with its predecessor, revision 69.

See also

For an explanation of the role of inspecting changes made in a working copy, refer to the Understanding the Subversion process recipe, earlier in this chapter.

To learn about applying changes to the repository, refer to the Committing changes to a Subversion repository using TortoiseSVN recipe, later in this chapter.

 

Updating a working copy and resolving conflicts using TortoiseSVN


This recipe explains how to update a working copy and how to resolve any conflicts that arise as the result of an update.

How to do it...

It is possible to update a part or all of a working copy. For continuity, it is generally best always to update the entire working copy. To perform an update, we use the context menu for the part of the working copy we want to update. TortoiseSVN provides us with two update options. They are:

  • SVN Update : Update working copy to the HEAD revision (latest repository revision)

  • TortoiseSVN | Update to revision : Update working copy to the specified revision

Durin g the update process, it is not uncommon to encounter conflicts. In the event that a conflict does arise, we will receive an error message identifying the conflict. Conflicts must be addressed as soon as reasonably practicable.

When we browse to the conflicted file, we will see the file highlighted as conflicted and three other helper files, originalname.ext.mine, originalname.ext.rX, and originalname.ext.rY. These files respectively contain the working copy that we hadwhen we tried to update, the base revision, and the HEAD revision. The conflicted file contains a mixture of the changes.

The TortoiseMerge tool can be used to resolve conflicts; we access this tool using the context menu TortoiseSVN | Edit Conflicts command. The following example shows a conflict in which the language strings LOREM and IPSUM have been appended to a file, and are now conflicting.

TortoiseMerge displays three of the four files—originalname.ext.rY (Theirs), originalname.ext.mine (Mine), and originalname.ext (Merged). We can select which of the changes we want to use from the Theirs and Mine panes. We can also directly edit the Merged pane. In this instance, we would likely take the changes from Theirs (using the right arrow in the toolbar) and manually copy the changes from Mine.

Once we have resolved the conflict, we can save the file and mark as resolved using the button on the toolbar, or the context menu TortoiseSVN | Resolved command. This will remove the helper files and allow us to continue development of our working copy. More importantly, it will mean that we are now in a position to successfully commit our changes.

Tip

Files can contain more than one conflict. In these instances, we can navigate through the conflicts using the up and down arrows in the toolbar.

How it works...

When we update our working copy, the changes in the repository are merged with our working copy. It is this merging of changes that enables Subversion to allow several users to work on the same file at once. Sometimes, however, Subversion will not be able to successfully merge the changes as demonstrated. For example, if two developers edit the same file by inserting new content, and that new content is inserted at the same location, Subversion will not be able to determine how to merge the sources.

This is where human intervention is required. It may be that the two developers have added content that does the same thing; therefore, one of those sets of changes needs to be discarded. On the other hand, the changes may need to be manually combined.

Note

A common source of conflicts when using Subversion to develop Joomla! extensions, are the INI language files, because new language strings are nearly always added to the end of the file.

See also

For an explanation of the role of updating a working copy, refer to the Understanding the Subversion process recipe, earlier in this chapter.

To learn about applying changes to the repository based on a working copy, refer to the next recipe, Committing changes using TortoiseSVN.

 

Committing changes using TortoiseSVN


This recipe describes how we commit changes to a Subversion repository.

How to do it...

To commit changes we make to our working copy, we use the context menu TortoiseSVN | Commit command. As with an update, a commit does not have to include the entire working copy.

The Co mmit dialog box allows us to select the files and folders—including unversioned files and folders—that have changed in our working copy that we want to include in the commit. We can also include a message. It is good practice to always include a message that briefly describes the changes that the new commit applies to the repository.

When we are happy with the selected changes that we want to apply, we simply click on the OK button. We will now be presented with a transcript dialog that will log the actions taken during the commit.

There's more...

Sometimes a commit will fail. This will usually be the result of inconsistencies in the working copy as the result of earlier failed Subversion actions. There is a quick and easy solution! Cleanup is an automated process that "cleans up" our working copy. To cleanup a working copy using TortoiseSVN, use the context menu TortoiseSVN | Clean up.

Tip

If using the TortoiseSVN cleanup command does not resolve the problem, try using the command-line client. This can prove more reliable. The command-line client cleanup command does not provide any output.

 $> svn cleanup H:\path\to\working\copy

Note

To get a copy of the SVN command-line client visit http://www.collab.net/downloads/subversion/.

See also

For an explanation of the role of committing changes from a working copy, refer to the Understanding the Subversion process recipe, earlier in this chapter. To learn how to apply other users' changes to your working copy, refer to the previous recipe Updating a working copy and resolving conflicts using TortoiseSVN.

 

Exporting a working copy using TortoiseSVN


This recipe explains how to export files in a working copy to a new location. This can be especially helpful when we come to package a release.

How to d o it...

There are two very useful options that dragging folders outside of a repository using the mouse context button provides us with. There are two export options that enable us to export the contents of the working copy without copying the Subversion metadata. The options are:

  • SVN Ex port to here: Exports the versioned files and folders to the new location (without the .svn metadata)

  • SVN Ex por t all to here: Exports all of the files and folders to the new location (without the .svn metadata)

About the Author

  • James Kennard

    James Kennard is a computer programmer. He has worked with various PHP and MySQL applications, since 2002. He quickly discovered Mambo/Joomla! because of its flexible extension manager. James currently maintains one open-source Joomla! component, which has been translated into over fifteen languages. Moreover, he has plans to build two more open-source components. Examples of his work can be found on his personal website www.webamoeba.co.uk.

    Browse publications by this author