OpenEDATools New Project HOWTO
Introduction
Hello new OpenEDATools user ! I'm writing this HOWTO in an effort to make
it easier to setup a new project at OpenEDATools. This document is
incomplete, (of course) and will hopefully be added to over time as more
features are added to OpenEDATools. My intention is for this to be a
step-by-step guide for the initial setup of your new project. First I
will outline what I think is the most common situation new developers
will face ; You have a directory of code, maybe even a current CVS
repository, and you wish to use all the features of OpenEDATools to
continue developing your project in the public eye, free, and open
sourced, and hopefully to attract some new developers to it, and, of
course, users. So let's get started...
Steps for setting up a new project
Here is a brief overview of what is involved, details to follow ;
1. Register as a new user with OpenEDATools.
2. Register a New Project, logged in as the user you created in step 1.
3. Setup your group and project information.
4. Create your CVS repository with the latest snapshot of your code.
5. Setup your group's web site.
6. Setup mailing lists for your project.
7. Finally, get used to using CVS for development, and get to work !
...and some other things that you may need ;
8. Release a file module so people can see your work !
9. Read the OpenEDATools site documentation and the help message forums.
Now on to the business...
1. Register as a new user with OpenEDATools.
On the OpenEDATools homepage, click on the option New User via SSL. This
will allow you to give your details to OpenEDATools, and it will then
setup a user account for you. To do just about anything involving
interacting with OpenEDATools you need to have a user account. Once this
is done, you can login as this user anytime using the Login via SSL
option on the OpenEDATools homepage.
When you login you are presented with your personal page ; any projects
you are involved in are listed, along with some other info. Along the
side of the page are some options for you, including one which is of
particular interest to us ; Register New Project...
2. Register a New Project, logged in as the user you created in step 1.
Clicking on the Register New Project link takes you to a set of pages
which you must simply step through, providing all the information
required. It is very straightforward and well setup, so no help here is
really needed.
Once complete, it gets sent to the OpenEDATools staff, and they look over
it to determine if your project would be suited to the goals of
OpenEDATools. I've yet to hear of a project rejected, so don't worry ; if
its open sourced and free, I think you'll get accepted quickly.
Now you wait, and hopefully receive a reply within 24 hours. (if it takes
longer, mail them directly - there were some problems with new projects,
but I believe they have been corrected now) If all goes well you will be
informed of your new project being up, and so login via SSL and at the
bottom of your personal page there will be a link to your new project's
group page...
3. Setup your group and project information.
Click on that link ! You will now see your group's OpenEDATools page (this
is different from your web site), and a list of options allowing you to
change things, basically to administer your project.
What do you have now ? Well, you have all of the following ;
a website at http://OpenEDATools.si2.org/projects/Your_Project_Name
a CVS repository at
cvs.openedatools.si2.org:/cvsroot/Your_Project_Name ,
anonymous FTP at ftp.openedatools.si2.org,
and access to mailing lists, which we'll use later.
The first thing to do is to enter a description of your project for your
group page. Click on Project Admin, and then on Edit Group public
Information and Categorization. Insert the required info into the fields.
Next question ; Do you have any other developers already ? If so, they
must all register as users on OpenEDATools, and then give you their user
names. You can then add them by user name to your list of developers,
giving them write access to your group's CVS and web site. To do this go
back to Project Admin, and click on Add Group Member. Now type in their
user name, and they will be added.
The rest of your group page you can explore and see what else is about. I
think we've done the most important things here. Time to get some code
where everyone can see it...
4. Create your CVS repository with the latest snapshot of your code.
For people new to internet development (as I am myself) CVS takes a
little getting used to. For the newbies, here is a brief description of
what it does and how ;
It keeps a record of every change made to the source code, along with
comments about that change. At any time you can see any previous version
of any file in the repository. It allows multiple people to work on the
same files at the same time, merging the changes as they are "committed",
and alarming the user if two changes conflict (very clearly, I might add)
making sure the difference is resolved by a human being before allowing
the new version of that file to be placed into the repository.
This is cool. It takes some getting used to however. Basically the
development cycle goes like this ;
(1) You import all your code into the CVS, then everyone "checks out" a
working copy of the source tree.
(2) Each person works in the comfort of their own computer generated
reality, and when they have a new feature working, they "update" their
local copy to be as much in sync with the current version as possible,
and then they "commit" the files that have changed, back into the
repository.
(3) Any problems CVS has with commiting the files will be mentioned, and
you must then go through the problem files and resolve the differences
manually. In the files, the changed section is highlighted with >>>>> and
both versions are shown. Simply delete the old version (or edit to make
it work how its supposed to), and re-commit the file. Once CVS has no
problem, return to step (2), and get back to work !
So, now to the details of importing your source tree into your CVS
repository at OpenEDATools. First read the site documentation on CVS. For
more info read a bit of the free 180 page CVS book. Then do the following
;
Get SSH and CVS for your platform. Under linux using a Bash shell, type
in the following ;
export CVS_RSH=ssh
export CVSROOT=Your_User_Name@cvs.openedatools.si2.org:/cvsroot/Yourct_Name
The first line tells CVS to use SSH to connect to the repository. This is
for security purposes. The second line tells CVS where to look for its
Repository.
Now, the most likely situation is that you have some source code in a
directory tree you wish to import into CVS. Go to the top directory you
wish to import, in your source code tree, and type in the following,
filling in the bits mentioned below ;
cvs import Directory_Name vendor start
Directory_Name is the name under which the repository will be accessed.
If all goes well it will ask for your OpenEDATools user password, and then
go on its merry way importing your whole source tree.
Next, backup your old code base somewhere, because you don't want to work
with it anymore, and checkout a fresh CVS version using ;
cvs checkout Directory_Name
This will get you a "working copy" of the code, in CVS form, ready for
you to hack on. You should remember, however, that any changes such as
adding/removing files and directories must be explicitly stated to CVS -
see the above mentioned book for details.
5. Setup your group's web site.
I'll assume that you have some sort of web page or site built already
that you wish to put up on OpenEDATools to give your group a public face.
Login to OpenEDATools using SSH, for example ;
ssh Your_User_Name@openedatools.si2.org
you will now be in your home directory. From here all group files are
stored in /home/groups/Your_Project_Name. Change to this directory. All
your web pages are stored in the ht_docs directory. Going in here will
contain index.php, which is a blank page that says you haven't uploaded a
web page yet. Logout, and copy the files for your web page using scp, a
program which comes with ssh. For example ;
scp Local_File_To_Upload
Your_User_Name@openedatools.si2.org:/home/groups/Your_Project_Name/ht_docs
I suggest you gzip up your site, send it in one go using scp, then login
with ssh and gunzip it.
So what should be on the web page ? Perhaps you'd like the following, as
well as your project's information ;
(1) A link to the projects group page on OpenEDATools.
(2) Mailing list links (we'll create them in a second)
(3) A OpenEDATools icon and web counter - see the site documentation for
this.
(4) A link to the CVS web interface at
http://openedatools.si2.org/cgi-bin/cvsweb.cgi/?cvsroot=Your_Project_Name
(5) Some info about using CVS specific to your project.
6. Setup mailing lists for your project.
If your project isn't that active yet (or only has one lonely developer)
your mailing lists will be very quiet, however I still suggest you look
to the future and setup three standard lists for your project ; a devel
list for developers, a users list for users, and an announce list for new
version announcements.
Do this via your group page using the mailing list admin link. Its quite
simple so you shouldn't have any problems...
7. Finally, get used to using CVS for development, and get to work !
I'll give you some quick details of the development cycle to get you
started, but anything you'll have to look up yourself.
To update your working copy to be in sync with the CVS repository one use
;
cvs -z3 update -Pd
(after setting up CVSROOT and CVS_RSH as outline previously)
For commiting the changes to a file ;
cvs commit -m "comment about changes." filename
To add a new file to the CVS repository ;
cvs add filename
cvs commit -m "added filename" filename
...and now you're ready to go !
Some other things that you may need ;
8. Release a file module so people can see your work !
9. Read the OpenEDATools site documentation and the help message forums
from the homepage. Recommended.
|
