Table of Contents
Adito SVN structure
You can see the Adito SVN structure by visiting the Adito viewvc page. The basic layout is like this (21th Feb 2009):
.
|-- adito
| |-- branches
| |-- tags
| `-- trunk
`-- adito-applications
|-- adito-application-elusivajavardp
|-- adito-application-properjavardp
|-- adito-application-putty-portable-ssh
|-- adito-application-putty-portable-telnet
|-- adito-application-tightvnc
|-- adito-application-tn5250j
|-- adito-application-ultravnc
|-- adito-application-ultravncproxy
`-- adito-application-winscp
The main Adito code is located under the adito directory. External, Adito-related projects such as applications are on the same level with Adito. The application directories contain the following
- a source directory, where unpacked application (=sources) are located
- a build.xml file that is used to create the application ZIP-file (whenever sources are modified)
- the actual extension ZIP-file
These Adito applications will be periodically pushed to the Adito Extension Store, which is enabled by default on Adito 0.9.1. As Adito is seeing a lot of restructuring right now (Feb 2009), we have three lines of development:
|-- branches | |-- maven2 | |-- nonembedded |-- tags | `-- release-0.9.1
The maven2 branch is related to the Ant -> Maven2 migration. The nonembedded branch helps in the maven2 migration, but it's main purpose is to get rid of the embedded Jetty and HSQLDB (=custom Context) while keeping the trunk functional at all times for developers that add functionality. The tags are just snapshots of the trunk at the time of a new release.
Subversion basics
This section is only a very brief introduction to the basic SVN concepts and commands. You should definitely take a look at the Official SVN book for more thorough information.
Basic terminology
Subversion server: The server component of Subversion. Manages the repository.
Repository: the (remote) repository which contains the versioned files.
Subversion client: The client component of Subversion. Several different ones are available. Downloads files from the repository and places them to a local working copy.
Working copy: Local copy of the repository. This is what developers work with. Will need to be updated periodically to keep it in sync with the repository. Changes to the working copy are submitted back to the server by doing a commit.
Revision: Version number of a file or a directory in the repository. Each commit to the repository creates a new revision.
Trunk: Usually the main line of development.
Branch: Branches are useful when invasive changes have to be made to which would render the trunk useless for a long time. When the changes to the branch are finished, trunk and the branch are usually merged.
Check out: The process of getting the (latest) files and directories from the repository and placing them in the working copy. Usually done only once - or when you want to start from scratch.
Update: The local working copy needs to be synchronized with the repository every now and then. You should always update your working copy before starting your work.
Commit: Pushing the changes in your local working copy to the repository. In some cases this may result in a conflict.
Conflicts and merging: If somebody else has made changes to same files as you, a conflict will be raised when you try to do a commit. In this case you need to resolve the conflict, either by merging the changes or discarding one set of changes. For more information, take a look here
Getting a Subversion client
To work with Adito Subversion repository you need to have a Subversion client. There are instructions for getting one in the Installing and running the Adito server. Only the standard, command-line Subversion client is covered here. The information presented here should be easy to apply to other SVN clients, though.
Checking out code from the repository
If you want to check out (=download) everything from the Adito Subversion repository, follow the standard instructions:
svn co https://openvpn-als.svn.sourceforge.net/svnroot/openvpn-als adito
This is, however, probably what you want. Here are a couple of more useful examples:
Check out all applications
If you maintain several Adito applications, it's probably easiest to check out all the applications at once, instead of getting each separately:
svn co https://openvpn-als.svn.sourceforge.net/svnroot/openvpn-als/adito-applications
Check out one application
If you maintain only one application, you can download just it:
svn co https://openvpn-als.svn.sourceforge.net/svnroot/openvpn-als/adito-applications/adito-applications-name_of_application
Check out the trunk
Most developers who do Java coding should probably download the trunk, where most of the development is happening:
svn co https://openvpn-als.svn.sourceforge.net/svnroot/openvpn-als/adito/trunk
Check out one branch
In specific cases it may make sense to download some development branch instead of the trunk:
svn co https://openvpn-als.svn.sourceforge.net/svnroot/openvpn-als/adito/branches/name_of_the_branch
Basic work cycle
Once you've checked out the code (see above), you usually proceed in this order:
1. Enter the working copy root and do a svn update to download the latest changes.
2. Make the changes you need to do.
3. Check the status of your working copy (changes, etc.) with svn status and fix any issues.
4. Commit your changes by doing a svn commit -m "Write information here about your changes"
For a much more thorough instructions, take a look at the Basic work cycle in the official SVN book.
Notes about committing to Adito SVN
In a community open source project like Adito you should commit your changes to the Subversion repository as soon as possible. That way other developers and advanced end users can start testing, fixing and enhancing the code. The old paradigm "release often, release early" is true even at this scale. If your commit breaks something, that's fine: ordinary users are not using code checked out from the SVN. Also take care to desribe your commits well, so that others can instantly see what kind of changes you made.
Advanced topics
Subversion properties
NOTE: The migration to Maven2 will probably make managing Subversion properties (mostly svn:ignore) much easier than what's described below.
Adito build scripts have changed in many ways after forking from SSL-Explorer. One of the most important things is that the temporary build directories are also versioned (=not deleted with "ant clean"). This allows attaching directory-specific properties to them.
One of the most important properties in use is svn-ignore, which is directory-specific and allows unversioned files to live in versioned directories. This property is needed because we have no direct access to the Subversion server itself - only to the repository. Thus we can't create hook scripts to do the necessary magic. Unfortunately using svn-ignore is not enough. You still need to define global-ignores in your Subversion client configuration (see below).
Setting svn:ignore property is quite easy and you should do it yourself if you add new directories. It's usually easiest to use a file containing the ignore patterns, like below:
user@server:~/opt/adito$ cat svn-ignores-global *.log *.log.? *~ *.class *.backup *.data user@server:~/opt/adito$ ls adito adito-application-tn5250j adito-application-winscp adito-application-putty-portable-ssh adito-application-vnc svn-ignores-global user@server:~/opt/adito$ svn propset svn:ignore -F svn-ignores-global adito-application-vnc/ property 'svn:ignore' set on 'adito-application-vnc' user@server:~/opt/adito$ svn propget svn:ignore adito-application-vnc/ *.log *.log.? *~ *.class *.backup *.data
If you are using Linux/*NIX you can easily set the svn:ignore property to a large number of directories all at once:
user@server:~/opt/adito$ find . -mindepth 1 -maxdepth 1 -name "adito-application*" -type d -exec svn propset svn:ignore -F svn-ignores-global {} \;
property 'svn:ignore' set on 'adito-application-putty-portable-ssh'
property 'svn:ignore' set on 'adito-application-tn5250j'
property 'svn:ignore' set on 'adito-application-vnc'
property 'svn:ignore' set on 'adito-application-winscp'
The mindepth and maxdepth parameters make sure that the search does not affect directories below or above this level. The type -flag ensures that find only touches directories.
Global ignores for the Subversion client
To make sure that commits don't commit unversioned files, such as the HSQLDB database files, private/public keys or configuration files, we use the svn-ignore-property in all Adito SVN repository directories (see above). In addition we need to modify the global-ignores in the Subversion client config. It's located in $HOME/.subversion/config on Linux/*NIX systems. The example below should get rid of most unversioned files:
# $HOME/.subversion/config # Global ignores for Adito. Add all to one line global-ignores = *.data *.prv *.pub *.jks *.conf *.backup *.log conf db prefs.properties *.script explorer_configuration.properties .classpath .project target assembly
With the nearly complete migration to maven2 (as of 30th July 2009) the need for client-side global-ignores will reduce dramatically.
NOTE: The svn-ignore-property or global-ignores in the client config don't have any effect on already versioned files. They have to be unversioned first with svn rm. Make sure you make a backup copy before removing them.
