SVN updated with historical versions [Archive] - ShowEQ Open Source Project Message Forums

bonkersbobcat

01-20-2008, 08:21 PM

I am no SVN expert, but here is what I have been doing...

NOTE: These instructions are for developers. They will get you the latest version of the SEQ code, but that version may not work. If you have write access to SVN (you probably don't) these instructions will show you how commit your changes to SEQ in SVN. If you are not a developer, it is probably best for you to wait for an announcement that a new tarball has been posted.

I assume that you have installed SVN on your machine.

SVN maintains a thing called a repository on the server which contains all the checked in versions of files for a project. The first thing you must do is to make a local copy of these files on your machine. This is done with the SVN "checkout" checkout command:

svn checkout https://seq.svn.sf.net/svnroot/seq/showeq/trunk

The "seq.svn.sf.net" portion is the address of the sourceforge SVN server, the "svnroot/seq/showeq" is the path to our project within sourceforge, and "trunk" is the directory or branch in the repository tree that contains the files being actively developed.

When you issue this command a "trunk" subdirectory will be created on your machine which will contain the SEQ project plus a couple of hidden SVN control directories.

The checkout command only has to be issued once. You will use different commands to refresh the files on your machine or to check stuff in.

The checkout command doesn't lock anything on the server. In fact, the server doesn't even record the fact that you checked something out. Any number of people can checkout a project. You don't have to be a developer or have any special permission to checkout.

From the trunk directory you can build SEQ and make whatever code changes you need to make.

Note that the build and configure systems are generally not put into source control so you will have to do a full "developer build" of SEQ. The first step of the developer build process embeds the SEQ version number into the project so if the build version number needs to be incremented, do it here. At the moment, the current version number is 5.12.0.0. If you just change opcodes or packet related structures or make minor code bug fixes, then bump the third digit (in this case it would be 5.12.1.0). If you change code that alters functionality such as adding or removing network encryption, or adding new features to SEQ itself, bump the second digit (in this case it would be 5.13.0.0).

The version number is contained in the configure.in file within the trunk directory. In about the 5th line of configure.in you will see a line like:

AC_INIT(showeq, 5.12.0.0)Edit this line to contain the new version number. Note: Only increment the version number once between announced releases, with "announced releases" meaning that someone creates a tarball and posts it on the boards. If you make three changes to opcodes and check them all in before a new version of SEQ is announced on the boards, the version number only needs to be incremented once.

First step for a "developer build" is to create the "configure" script:

build -f Makefile.dist build
then you have to create the makefile (run the configure script.) If you have been working with the tarball in the past, you would have normally been starting here in the build process.

./configure
and then actually build the project

make
and then install and run it

sudo make install
sudo chmod +s /usr/local/bin/showeq
showeq

On my machine the build breaks in main.cpp with a reference to UTS_RELEASE. I just edit main.cpp to comment out the references to UTS_RELEASE. I plan on checking in those changes with this next round so that will longer be an issue for folks.

At this point you should have a properly compiling build environment that is under the control of SVN. Make whatever changes to the opcodes, structs, or program code is necessary and recompile and test. When you are ready to check stuff back in, do the following steps:

Note: It is generally considered bad from to check stuff in that won't compile. It is ok if you only have some of the opcodes or have structures that aren't completely correct (but better then they were), but please, please, please make sure that the project will compile without error before you check in.

First you need to make sure that no one else has checked in any changes after you did your checkout or last update. There are only a few people that have permission to check stuff into SEQ so this is not likely to happen but it is a good idea to check anyway. Execute the following from trunk directory:

svn update
SVN will update your files with the ones on the server and give you a report of what it did. For any file that you have not changed, but has been changed on the server, it will bring those new files down to your machine. If you have changed a file that has also been changed on the server, it will report a conflict. If nothing has changed on the server and you are up to date, it will just print out something like "At revision xxx". Before proceeding make sure that there are no conflicts. You can type
svn help updatefor more information.

Next, update the ChangeLog file in the trunk directory to indicate what has been changed. Try and keep the format consistent with the existing entries. The most recent entry looks like:

BlueAdept (12/16/07)
----------------
Updated version to 5.12.0
Updated Opcodes (ieatacid)
Removed all the obfuscator stuff (ieatacid)

Next you need to tell SVN if you have added or removed any files from the project. Normally we are just updating the opcode XML files and the structures in the everquest.h file, so you don't have to do this. But if for some reason you have created a new file or deleting a file from the project, you need to issue the appropriate SVN command:
svn add <filename>
svn delete <filename>

Next you want to review your work and make sure what are about to check in is what you actually intend to check in. This is important because you can't really undo a check in. Type the following command from the trunk directory:

svn status
This will print out a list of files that are different on your machine then are are on the server. You should see a "M" in front of the files that you have changed (this means that SVN sees your version of the file as modified) and a "?" in front of files that are on your machine, but not in the project. If you added or deleted files you will see files with the "A" or "D" status. If you see any other status codes, check the help in SVN and resolve the issue before proceeding.

Note that there will be lots of files with the "?" code, this is because the SEQ build process generates all sorts of files. Nothing will happen with the "?" files when you do the check in, so it is ok to ignore these, but you do want to scan the list to make sure that none of the files listed are ones you added to the project and forgot to issue the "svn add" command for. Don't add the generated files to the project as that is generally a bad practice.

If you want, you can issue a
make distclean command from the trunk directory to clean up most of the generated files and make it simpler to review the list file with a SVN "?" status. If you do this, you will have to go though the full build process again. Even after a "make distclean" there will be some "?" files (decomp, config.h.in, autom4te.cache, missing, aclocal.m4, and install-sh) This is normal, don't add these to the project.

Next issue the following from the trunk directory:

svn diff | less
This will show you all the changes that you are about to check in. Double check that these are the changes you have made.

Now, finally, issue the following command from the trunk directory to check in your changes:

svn commit --username xxx --password yyy
Replace "xxx" and "yyy" with your sourceforge username and password. Of course, only the people who have been granted write access to the project can do this.

When you issue the "svn commit" command an editor will pop up and prompt you to enter a description of the change. It is important to do this, as this text will be prominently displayed when people use the web to browse the source tree. I have been entering a slightly less verbose version of the ChangeLog entry. For example the description of my last check in looked like:

Historical checkin for 12/16/07
- Updated Opcodes
- Removed all the obfuscator stuff

Version to 5.12.0
When the editor pops up, it will contain a line that says something like "-- this line and everything below is ignored --" with a list of the files modified below that line. Just insert something like my example above the line and exit the editor. Help for the key to get out of the editor is on the bottom of the screen, I think it is ctrl-x.

And finally, if the check in is going to be an announced release (a tarball generated and posted) it is important to create a "tag" in SVN. A tag is a label that allows someone to check out all of the files as they existed at that point in time. We create tags with each release so that if someone wants to go back to a prior release they can do so easily. To create a tag, issue the following svn command:

svn copy https://seq.svn.sf.net/svnroot/seq/showeq/trunk https://seq.svn.sf.net/svnroot/seq/showeq/tags/v5_12_0_0 --username xxx --password yyy --message "Tag for release 5.12.0"

Replace xxx and yyy with your sourceforge account and password and be sure to update the message parameter with the new version number. Also be sure to update the destination path (the tag) with the new version number as well. Remember, only create a tag if this is an "announced release" that is getting a tarball published on the boards.

If you are creating an "announced release", use the following command to create the tarball:

make dist

Hope all this makes sense.

BB