Initial checkout

Once you have subversion you need to check out add1. Checking out the repository creates a LOCAL copy on your machine.

To checkout simply run the command from somewhere on your path: svn checkout http://svn.wp0.org/add1 ./somepath.

Aoirthoir's preferred method is: cd ~ mkdir SVN cd SVN svn checkout http://svn.wp0.org/add1 ./add1

This helps keep it organized, especially if you have other repositories that you work with besides add1tocobol. Make sure you have a lot of room in your home partition.

Committing

To commit changes (whether additions, changes to files or deletions) you have to have a username and password. If you do not, please see Aoirthoir (Joseph James Frantz) for permission. When you create directories and files in your add1 directory, they are not considered part of your repo, even though they are in the same place. To add them to the local copy of the repo (to be commited to the central copy later):

To add a file to: svn add filename

To add a directory with all of its files: svn add somedir

NOTE: adding files only adds them to YOUR LOCAL COPY of the repo. The same goes for changes, the changes are made ONLY TO YOUR LOCAL COPY and deletions are only deleted from YOUR LOCAL COPY. When you are satisfied with your changes you need to COMMIT them UP to the repository.

First get the latest, to see if there are any conflicts: svn up (or svn update)

Then to commit your changes: svn ci -m "Some message about WHY you are changing things..."

Alternatively if your commit message is going to be long: svn ci

This version will call up your default editor and then you can type in a very long commit message. Save and exit and subversion will grab the temporary file and commit.

Status

To see what would be committed before commiting: svn status

NOTE: Moving ADDED, DELETED, CHANGED or COMMITED files in any svn repository should NOT be done with your systems mv and cp/copy commands. These need to be done with svn commands. The svn commands are very similar to the typical system commands, cp, mv and rm. Use these commands like you normally would but preced them with svn as follows:

svn mkdir somedir svn mv oldfile newfile svn mv file dir/ svn mv olddir newdir svn rm file svn rm dir svn cp oldfile newfile svn cp file dir/ svn cp oldir newdir

What if you make a mistake? Change a file and wish to go back to your last update command?

To revert all files in a directory: cd dirname svn revert

or

svn revert dirname

To revert a single file: svn revert filename

There is of course a lot of information about Subversion and you can find links here: http://subversion.tigris.org/

and their book here:

http://svnbook.red-bean.com/

I HIGHLY recommend you read this book. I have only given a bit of information about what can be done with subversion. But it is AMAZINGLY powerful and a full read of this free book is worth your time, not only for add1 projects, but all of your work, professional or personal. Additionally you can purchase a bound copy from Oreilly if you would like to have it in print.

PLEASE READ THIS SECTION

You will note several directories in the add1 root:

copybooks/ examples/ extensions/ libraries/ programs/ tools/ scratchpad/

Each of these (except copybooks) will have a similar structure:

projectname/

And if the project is large enough with enough developers: projectname/tags projectname/branches

This howto will be updated in the future to explain the concept of tagging and branching AS IT APPLIES to SUBVERSION...If you are already used to tagging and brancing from your version control software *please* be aware that subversion has a different take on it...so please hold off on tagging and branching unless you are already familiar with the subversion concepts.

Each of the directories has a specific purpose. But do not get too lost in trying to decide if something should be in one or another place. SVN gives us the ability to easily move things around, while retaining the history of the individual file or directory. These below are guidelines to help you move foward and stay organized. In all cases except copybooks, please add a directory for your project, with its name, and keep all files related to that project in one place. Please do not put some files for projA in extensions and others in libraries. If your project warrants such separation, please create two separate projects with different names.

Copybooks is specifically for GENERAL PURPOSE .cpy files. There will be .cpy files in the other directories, specific to those projects. This, rather, is for copybooks that are so generic, but fall outside of the scope of either a library (more next) or an extension. Copybooks can generally just be dropped into the main copybooks directory, no need to create a project name unless you are creating perhaps tens of dozens of copybooks. Some examples for the copybooks directory:

statcodes.cpy keycodes.cpy screencolors.cpy

Examples are code samples. They are not intended for inclusion into applications, but rather demonstrate how to accomplish something in COBOL, and Open Cobol specifically. When you add files to this, please treat similar types of routines as if they were a project. So we could expect to see:

examples/databases examples/screenio examples/web examples/sort

In fact, such examples, though not meant to exist on their own for inclusion into a project, could be used to form a template for a coder. Thus, having the basics down, she could modify the template code to fit her own needs.

Extensions is for any code that extends the power of Open Cobol itself. In theory this would be routines that could eventually be folded into the compiler itself. That is, they would be code that could be used by just about any project compiled with open cobol. (This precludes industry specific code, which would go into the libraries directory, more on that soon). Thus extensions tends towards more generic routines. Some examples:

cobxref cobdbi cobSQLite

General math functions, datgabase access graphics functions (gtk+, qt etc) connections to other systems such as: mono, php, perl, python and so on.

Libraries on the other hand, while also somewhat generic routines, in that they are intented to be used by other programs, are more specific. They would include libraries for specific industries, or specific types of programs such as:

Medical Data libraries (hcpcs, icd9) Accounting and Tax Routines to be included in accounting programs Baseball card routines to be included in sports programs

Essentially anything that is of use beyond one program. Now it might start that your routines remain in with your application in programs (more on that next) and then later you and others realize the value of a specific routine beyond that, so then at that time you could move to libraries.

Programs is specifically for users programs. A user program can be anything including:

A payroll system Medical billing baseball card collection video game You name it.

Scratchpad is for experimenting. When you are not quite sure what you will do with the project, or if it will even become a project. Or when you do not want to clutter your other project, but you want to have a history of your changes. However, please keep changes in this directory to a minimum, so that the add1 repo is not cluttered. If you tend to use it a lot, please see aoirthor and he will create your own repository for playing around with.

To keep scratchpad most clean, please create a directory name (generally your username or handle) so that folks know to keep out...)

Tools is VERY similar to Programs, with one key difference. The users, in this case are developers. So the types of programs that would go here, are things that will make your job as a programmer go easier for instance:

IDE Editor Configurations for existing editors debug tools, code formatters, code generators and so on...

That just about wraps up this howto. One thing that we ask you to keep in mind, is that all users are being trusted with access to the entire repository. We can set up Subversion so that only certain people can change certain things. However, this will be an added layer of hopefully uneeded work. Instead, we are placing trust in the users, to be careful what they do. If you need help you can always contact me (aoirthoir, JosepH James Frantz) at:

aoirthoir@add1tocobol.com aoirthoir on freenode irc 440-521-7214