Tag Archive for 'best practices'

Page 2 of 2

Busy Developer’s Guide to Subversion Best Practices

Need some quick tips on Subversion best practices, covering everything from structuring your repository, to avoiding merge hell, and advice on testing? In this post, we share some rapid-fire advice for busy developers who need to get the most out of Subversion straight away.

Repository Structure

Subversion gives users the freedom to structure their repository according to a project’s particular needs, but if you don’t implement a logical project layout, you’re running the risk of creating an administrative nightmare. Here are some general rules worth bearing in mind when creating a new Subversion repository, to ensure all that freedom doesn’t lead to complications!

  • The trunk shouldn’t break – the trunk should always be stable, and should always compile. To ensure the trunk doesn’t break, all risky development should be confined to the branches, and CI and automated regression testing should also be considered, to ensure there is no regression in the trunk.
  • Use tags – tags should be used to make snapshots of your project at certain points along the development process (e.g tagging a copy of ‘Release 1.0’.) It can also be useful to make snapshots of your code before implementing major new features, in case you need to roll back to before a feature was introduced.
  • Working copies should always be checked out from the top level of the branch/trunk – i.e /trunk or /branches/(branch name)
  • The root directory of the working copy should be named after the branch that it is checked out from (e.g “ProjectA”)
  • Make structural changes to the trunk – structural changes to the repository (directory or file renaming, and directory or file deletion) should always be performed on the trunk, at a time when there are no outstanding branches waiting to be merged. This can help teams avoid serious merge conflicts.

Want more advice on setting up your repository? For more information, see our post Subversion Best Practices: Repository Structure

Branching & Merging

Branching and merging can be a pain-point for Subversion users, but when used correctly, branching and merging is one of the most powerful tools at your disposal. Here are some tips for avoiding merge hell – and that dreaded merge conflict!

  • Make use of log messages – when performing merges, it is good practice to leave as much information in the log message as possible (what changes were made, why, and by whom, etc.) Remember, the more information you provide, the easier it will be months down the line, when you need to find out if a particular branch was ever incorporated into the trunk.
  • One thing at a time – when performing a merge, it is important to isolate the merge (i.e only make changes that are necessary to resolve the conflict) – do not add any additional planned development before performing the commit. Likewise, do not commit unrelated code changes in the same commit (i.e two bug fixes in one commit). Both of these actions make it difficult to distinguish where changes originated from, and can cause major headaches if the team decides to roll back to a particular revision.
  • Use branches – branches should be created for new features and major bugs. Bug fix branches are particularly useful, as they allow bugs to be worked on immediately, regardless of the work underway in the trunk, or in neighbouring branches.
  • Use ‘svn update’ – branches should be kept up to date with changes committed to the trunk, by regularly running ‘svn update’. Even if it seems your changes have little to do with the rest of the team, by the time you’ve finished perfecting your branch, the trunk may have evolved to the point that it’s a nightmare to merge your changes.
    It is good practice to also run ‘svn update’ on the working copy before you begin making any changes. This ensures that your working copy is up to date with the latest version in the repository.
  • Commit often – commit small changes frequently, as oppose to committing many small changes in one large chunk. This will help reduce the chances of encountering merge conflicts, and will help reduce the complexity of conflicts that do occur.
  • Delete unwanted branches – branches that are no longer required can be deleted. There are several reasons why you may decide to delete a branch, but the main ones are:

    – To reduce clutter.
    – A successful merge has been performed, and the branch is now redundant.
    – A successful reintegration merge has been performed, and any future reintegration of that branch will confuse Subversion’s merge tracking capabilities.

Branches should not be deleted to reduce the repository size, as deleting branches does not actually remove them from the repository, it just removes them from the HEAD revision.

For even more information on branching and merging, check our out blog on Best Practices for Merging in Subversion

Testing

And lastly, test everything! Get into the habit of systematically testing every feature and bug fix implemented after merging, and consider CI and assertion testing on feature branches, which are useful for indicating code maturity and progress. As a minimum, automated regression testing should occur on the build of the feature branch.

Subversion Best Practices: Repository Structure

Maintaining a Subversion repository can become a complex task, and implementing the right project layout from the very beginning is crucial. As Subversion doesn’t impose a strict file structure, users are free to tailor Subversion repositories to their project’s needs. Users can organize Subversion on a ‘one project per repository’ basis or create multiple projects within the same repository; and have considerable freedom when it comes to how they use Subversion’s trunk and branches. In this post, we’ll look at some guidelines and best practices on how to keep Subversion files, for users who are embarking on a new project in Subversion.

Multiple Projects: Single Repository vs. Multiple Repositories

In modern software development, it’s normal for teams to be working on multiple projects simultaneously. If this sounds like your organization, the first question you’ll need to answer is: should I set up a single repository for multiple projects, or create one repository per project? Although the experience will be slightly different for each project, there are some general benefits and drawbacks to each approach.

Single Repository

Single repositories are typically suited to organizations managing multiple, small projects that require cross references, cross tracking, etc.

Positives:

  • there is a single location where all the code is stored, even for projects you aren’t directly involved in.
  • ability to reuse common libraries.
  • lack of duplicated maintenance (e.g only one repository needs to be backed up.)
  • the ability to move data between projects more easily, and without losing any versioning information.
  • all projects share the same repository history.
  • typically less administration – new projects can be created without creating a new repository, and without the help of sysadmin.
  • you can delete entire projects without losing the record from Subversion.

Negatives:

  • Subversion uses repository-global revision numbers which apply to entire trees, not to individual files. The revision number for projects will increase in accordance with the rest of the repository, even if no changes have been made to that particular project.
  • unable to use unified logging (svn log command).
  • branching can be complex when many folders and files are involved.
  • dumping/loading one huge repository can be time-consuming.

Multiple repositories

These are typically suited to multiple large unrelated projects.

Positives

  • the ability to define different access permissions, for different users.
  • each project repository will have its own revision sequence.
  • the version number is meaningful for all projects.
  • projects have a tendency to increase in size, and numerous large projects on a single repository can become difficult to maintain. It is typically easier to manage large projects with a ‘one repository per project’ approach.
  • can tailor each repository’s structure to suit a project’s unique needs. This can include branching, tagging, naming conventions, etc.

Negatives:

  • Subversion does not support merging code between projects in different repositories, and the transplanted code will appear in the new repository with no history. This also means you cannot perform merges if you need to temporarily maintain two versions of related code.
  • different projects have different mailing lists, which can be a problem if there’s cross-over between two related, but separate, projects.

There is also the potential to have more than one repository, and to group related projects within the same repository. This allows related projects to share data, and when new revisions are added to a repository, they are more likely to be relevant to everyone who uses the repository.

Project Layout

Once you’ve decided whether to organize your projects in a single or multiple repository structure, it’s time to plan your project layout. Putting some thought into your layout in the beginning, can help you avoid having to move files around later.


An illustration of how a Subversion Repository evolves using branching, tagging and a code trunk.

Here are some best practices for getting the most out of your project layout:

  • Project root – This is the anchoring point for a project. A repository may contain one project root, or multiple roots, but each project root contains three subdirectories: /trunk, /branches, and /tags. The use of a project root is officially recommended by the Apache Subversion project.
  • Trunk – This is where you should store current release code – only! Don’t muddy the trunk directory with revisions or release names.
  • Branches – Use these to work on significant changes, variations of code etc, without disrupting the current release code.
  • Bug fixing on a branch – Branches should be created to fix major bugs; this allows bug changes to be immediately worked on without disrupting whatever work is currently underway in the trunk/development branches.
  • “Toe in the water” branches – Branches can be used as a code “sandbox” where new technology can be tested without risking the working code. If things go right, the new code can always be merged back into the trunk.
  • Tags – Should be used as “code milestones” providing a snapshot of the code at specific points in its history.
  • Tagging bug fix / development branches – when creating a code or bug fix branch, it’s useful to create a “pre” tag, and a “post” tag after the bug fix or code change has been completed:

http://10.2.5.2:9880/encom/tags/PRE_authchange_bug9343
http://10.2.5.2:9880/encom/tags/POST_authchange_bug9343

Ready to start a new project with Apache Subversion? Certified open source Apache Subversion binaries can be downloaded from the WANdisco website.