[csjava-developer] csjava Project FAQ (version 3)

[Toby D. <tj...@sf...>]

csjava Project FAQ (version 3)

What is the csjava project?

The csjava project is an open source software project aimed at developing
fun and instructive software for Java and CS courses. It includes (but is
not limited to) the design, implementation, testing, and documentation of
programs related to:

   - image processing
   - multimedia programs (e.g. MP3/MPEG players)
   - speech generation
   - 2D animation
   - language and string processing code
   - helper code for beginning and intermediate (and beyond) CS courses
   - a MACM package (i.e. code useful for people taking MACM 101/201)
   - a parallel processing package
   - code for creating chat-bots that run on Jabber servers
   - demo/example code showing off fun/interesting/important aspects of CS
   - anything else related to CS and Java that a csjava developer wants to
contribute!

In a few weeks, we may also be be looking for help setting up some a
parallel Knoppix system in the Surrey labs, and possibly even creating an
SFU-specific distribution of Linux for education (e.g. based on Knoppix).
We'll post to the mailing list when we know more.


What is the current state of development?

We've already created (and used in CMPT 125 and 225) some of the image
processing code, namely TheMatrix. You can download the current release of
the csjava.jar file here: https://sourceforge.net/projects/csjava/ (the
current release is named "stimpy"). As you can see, there is not yet any
documentation for how to use this. Any volunteers willing to write an
introductory tutorial? :-)


If I join, how much work is involved?

Since this is a volunteer project, you can do as much or as little as you
like. It's up to you. You can join and just watch and explore for a while to
see if there's anything that interests you. Or you could volunteer to be the
lead for one of the above sub-projects, which will require a little more
commitment. But imagine the glory! :-)

The most useful and interesting code will be included in future releases of
the csjava project. If you are inactive on the project for a long time, you
will probably be dropped from it.


I'm not a Java expert. Can I still help?

Definitely! Helping out on this project is a great way to learn Java, or
refresh your memory of it. Or, if you prefer, you can work more on the
documentation aspects of the project (currently the project is sorely
lacking good documentation, and help on this would be extremely useful to
many people).


What if I have an idea for something else that I want to do for this
project?

Great! We welcome new ideas, especially if they are based on code that's
already in the csjava package. Suggest your idea to the group mailing list,
and see what people say. Or when its done, send a request for people to try
out your code --- but keep in mind that most people will probably only want
to try out code that is fun/interesting or does something useful for them.
Getting other people to use (and improve) your code is strongly encouraged.


How do I join?

The first thing to do is to subscribe to the csjava-developers mailing list:

   https://lists.sourceforge.net/lists/listinfo/csjava-developer

This is the place to ask questions, get help, propose new ideas, discuss
design choices, announce new code for the project, etc.

The project itself is on SourceForge, a website that hosts open source
projects: https://sourceforge.net/projects/csjava/


How do I get started?

To become an official developer listed on the project page, you must join
SourceForge to get a username. This is free and easy. Once you've got your
username, email it to me (tj...@sf...) and you will be added as a developer.

The next step is to learn how to download code from the CVS tree. This has a
bit of a learning curve, but it is very useful and learning how to use CVS
now is good experience for future projects you may work on that use version
control.


What is the CVS tree?

CVS is a popular version control system that keeps track of all the
revisions to files in a project. All the csjava source code is stored in a
CVS tree on SourceForge, and your first task is to get a CVS client up and
running so that you can access the tree. If you want to browse the files in
the tree, look at the csjava folder here:
http://cvs.sourceforge.net/viewcvs.py/csjava


What's a CVS client? Which one should I use?

A CVS client is a program that runs on your computer, and it talks to the
main CVS tree. You use the client to download code from the tree, and upload
changes. Eclipse has an excellent built-in CVS client, and you are strongly
encouraged to use that one. It is quite easy to use compared to many other
CVS clients. You are not required to use Eclipse; you can use and IDE or CVS
client you like.


How do I set up the Eclipse CVS client?

You must follow these steps carefully! CVS is notoriously finicky, and a
single wrong character can result in bizarre and cryptic behaviour. But once
you get it working, it's pretty good.

  - First, you must be part of the csjava project, i.e. your name must be on
the developers list of the project (check
https://sourceforge.net/projects/csjava/). If your name isn't there, then
get a SourceForge name and get send it to one of the project administrators
so you can be added to the project.

  - Second, run Eclipse and open the Window menu, then Show View, and then
choose Other. Open the CVS folder, and select "CVS Repositories".

  - Third, add the csjava repository by clicking the icon for Add CVS
Repository, and then fill in the form that pops up with the following
information:

  Connection type: extssh
  User: your SourceForge user name
  Password: your SourceForge password
  Host: cvs.sourceforge.net
  Repository path: /cvsroot/csjava

Select both "Use Default Port" and "use the repository identification string
as the label". Double-check that you've entered everything correctly.

  - Fourth, if the previous step went well, you can now check out the CVS
tree, or parts of it. Lets check out a copy of the csimage folder in the
HEAD branch. First create a new Java project in Eclipse. Just create it, and
don't add any files. Then in that project choose "import", and choose
"Checkout Projects from CVS". The wizard will step you through checking out
the project.


I tried the previous steps, and it doesn't work. Help!

As mentioned, CVS is tricky to set up at first. But it does work, and
Eclipse makes using CVS about as easy is possible. The first thing you
should do is check that you've typed all the CVS repository information
correctly. A single mis-typed character will cause problems.

Some errors may be due to temporary problems, such as a network delay. Thus,
starting all over from the beginning is sometimes helpful.

If you're stuck, email the csjava-developers list and ask for help. Be as
specific as possible about why its not working. Give specific details, and
error messages (if any!).


What is updating? What is committing?

In CVS terms, "updating" means updating your personal copy of the CVS tree.
Committing is when you upload your changed version of a file to the CVS
tree. Update frequently, and commit only when you have finished, tested
changes.


What rules should I follow when I start out using CVS?

It takes some time to get familiar and comfortable with CVS, so when you
first start out please don't modify any of the files in the HEAD branch.
Make your package in the "developers" package, and practice there for a
while until you get the hang of it.


Who can commit what files?

Anyone can modify any files. But please, don't modify files outside of your
developer package without discussing your changes with others. This is
especially important for code used by lots of other programs --- even small
changes could break lots of code. When in doubt, please ask!


Okay, I've the CVS stuff working. Now what?

Now improve the csjava package! Pick one of the features mentioned in the
list above, and start to work on it. You should email the csjava-developers
list before you start just in case someone else is also working on the
project. If you are not sure about what to work on, then email the list or
one of the project administrators to get a particular task to work on.


You say the project is "open source". What does that mean?

All the csjava source code is freely available to anyone to use or modify as
they wish. The development is done on SourceForge, which is a hosting site
for open source projects. Even code that does not end up in the main release
will be made publicly available.

Finally, this is a shared project that depends upon the care and good will
of the developers. Many people depend on the code in this project, so strive
to be helpful, cooperative, and considerate. And have fun!