Joomla! 1.5 Development Cookbook

it.

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 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.orgSubversion repository.

Assembla Messages Tool can be used to this effect.

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

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

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

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

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).

SourceForge Documentation Plugin can be used to this effect.

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

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

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 whilehttp://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.

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:

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.

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.

How 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