xenocara/app/fvwm/docs/cvs.html

250 lines
8.8 KiB
HTML

<html>
<head>
<title>The Official FVWM Homepage - CVS Procedures</title>
</head>
<body BACKGROUND="black-stone1.jpg"
bgcolor="#000000" text="#ffffff"
link="#FFFF88" vlink="#EEDDDD" alink="#ff0000">
<center>
<h1><font color="pink">The Official FVWM Homepage - CVS Procedures</font></h1>
</center>
Fvwm2 development uses a CVS server.
<p><b>Note:</b> the state of code in the CVS repository fluctuates
wildly. It will contain bugs, maybe ones that crash the program. It
may not even compile for you. Consider it alpha-quality code.
You have been warned.
<H2> <font color="turquoise">Overview</font></h2>
To know what is going in with the source tree you should be reading
mail on the Fvwm Workers List. See the <a
href="mailinglist.html">Mailing List Info</a> page for more
information.
<p>To build fvwm2 from the CVS sources, you need to have several <a
href="http://www.gnu.org/">GNU</a> tools:
<ul>
<li>the <a href="http://www.gnu.org/software/cvs/cvs.html">CVS</a> client
version 1.9 or better,
<li><a href="http://www.gnu.org/software/gcc/gcc.html">GCC</a>,
<li>GNU <a href="http://www.gnu.org/software/make/make.html">make</a>,
<li><a
href="http://www.gnu.org/software/autoconf/autoconf.html">autoconf</a>,
version 2.13 or better, and
<li><a
href="http://www.gnu.org/software/automake/automake.html">automake</a>,
version 1.4 or better.
</ul>
<H2> <font color="turquoise">The Initial Download</font></h2>
To make life easier on yourself, create the file `~/.cvsrc', and
insert the following lines. These set useful default options for the
three most used CVS commands. Do this now before going any further.
<pre><font color="yellow"> diff -u -b -B
checkout -P
update -d -P
</font></pre>
Also, if you are on a slow net link (like a dialup), you'll also want
a line saying `cvs -z3' in the file. This turns on a useful
compression level for all cvs commands. Setting it higher will only
waste your CPU time.
<p>Before you can download development source code for the first time,
you must login.
<pre><font color="yellow"> cvs -d :pserver:anonymous@cvs.fvwm.org:/home/cvs/fvwm login
</font></pre>
The password is `guest'. The command outputs nothing if it works, and
an error message if it failed. You only need to log in once; all
subsequent CVS commands read the password stored in the file
`~/.cvspass'.
<p>Next, you checkout the latest source code.
<pre><font color="yellow"> cvs -d :pserver:anonymous@cvs.fvwm.org:/home/cvs/fvwm checkout fvwm
</font></pre>
This creates a "fvwm" directory in your current directory. Get in
there and get to work.
<pre><font color="yellow"> cd fvwm
autoreconf
</font></pre>
You <em>did</em> remember to install autoconf and automake, right?
<p>Once you are inside the working directory, you no longer need the
long "-d :pserver:..." argument when issuing cvs commands.
<p>CVS commands work from <em>anywhere</em> inside the source tree,
and recurse downwards. So if you happen to issue an update from
inside the `docs' subdirectory, it will work fine, but only update the
docs. In all of the following command examples, we assume that you
have <font color="yellow">cd</font>'d to the top of the fvwm source
tree.
<H2> <font color="turquoise">Code Updates</font></h2>
From time to time, the dedicated FVWM Workers will make changes to the
cvs repository. Announcements of this are automatically sent to the
fvwm-workers list. You will want to be subscribed to this list!
<p>You can update your copy of the sources to match the master
repository with the update command.
<pre><font color="yellow"> cvs update
</font></pre>
<H2> <font color="turquoise">Hacking the Code</font></h2>
So you've found a bug you want to fix? Want to implement a feature
from the TODO list? Got a new feature to implement? Hacking the code
couldn't be easier. Just edit your copy of the sources. No need to copy
files to `.orig' or anything. CVS keeps track of the original files
for you!
<p>When you have the code in a working state, generate a patch against
the <em>current</em> sources in the CVS repository.
<pre><font color="yellow"> cvs update
cvs diff -u &gt; patchfile
</font></pre>
Mail the patch to the fvwm-workers list with a description of what you
did. But read the FAQ file about ChangeLog entries before doing so.
<H2> <font color="turquoise">Conflicts</font></h2>
If someone else has been working on the same files as you have, you may
find that you have made conflicting modifications. You'll discover this
when you try to update your sources.
<pre><font color="yellow"> cvs update
RCS file: /home/cvs/fvwm/fvwm/fvwm/icons.c,v
retrieving revision 1.5
retrieving revision 1.6
Merging differences between 1.5 and 1.6 into icons.c
rcsmerge: warning: conflicts during merge
cvs server: conflicts found in fvwm/icons.c
C fvwm/icons.c
</font></pre>
<font color="green">Don't Panic!</font> Your working file, as it
existed before the update, is saved under the filename
`.#icons.c.1.5'; hence you can always recover it, should things go
horribly wrong. The file named `icons.c' now contains <b>both</b> the
old (i.e. your) version and new version of lines that conflicted. You
simply edit the file and resolve each conflict by deleting the
unwanted version of the lines involved.
<pre><font color="yellow"> &lt;&lt;&lt;&lt;&lt;&lt;&lt; icons.c
XpmImage my_image = {0}; /* testing */
=======
&gt;&gt;&gt;&gt;&gt;&gt;&gt; 1.6
</font></pre>
Don't forget to delete the lines with all the "&lt;", "=", and "&gt;"
symbols.
<H2> <font color="turquoise">Getting Other Versions</font></h2>
Sometimes you may want to get a specific version of the sources. For
example, let's say you want the sources as they existed for 2.1.5.
<p>Since you'll want to check out a fresh copy of the sources, you'll
need to <font color="yellow">cd</font> out of the fvwm source tree
before issuing the following command.
<pre><font color="yellow"> cvs -d :pserver:anonymous@cvs.fvwm.org:/home/cvs/fvwm checkout -r version-2_1_5 fvwm
</font></pre>
This creates a directory called `fvwm', with the sources as they
existed for the version 2.1.5. There may be other tags in the
repository, and you can use them as parameters for the `-r' option.
Do <font color="yellow">cvs status -v README</font> for a list.
<H2> <font color="turquoise">Getting Commit Access</font></h2>
Using the procedures described above, and being on the workers list
are a pre-requisite to gaining update access. We expect to have heard
from you more than once on the fvwm-workers list so that we have some
idea who you are.
<p>Doing some testing, submitting some patches, and getting involved
in the discussions will help us know about you.
<p>After you have been involved for a while, if we don't suggest it, then
ask. The fvwm2 development team is not a closed environment, we
welcome new members. There are no required duties, all work is
strictly voluntary.
<p>If there is agreement on the list that you should be given update
access, you will need to choose a CVS user ID and provide an encrypted
password. The latter can be obtained with the following Perl snippet:
<pre><font color="yellow"> perl -e 'print crypt("yourpass",join("",((a..z,A..Z,0..9)[rand(62),rand(62)]))), "\n"'
</font></pre>
Change 'yourpass' to whatever you want your password to be.
<p>Once you have update access, re-do the "login" command above using
your CVS user ID in place of 'anonymous', and your password in place
of 'guest', and you are on your way.
<H2> <font color="turquoise">Starting a Project</font></h2>
Discuss your ideas on the workers list before you start. Someone may
be working on the same thing you have in mind. Or they may have good
ideas about how to go about it.
<p>If you just have a small patch you want to make, you may just
commit it to the main branch. If the change is large, and lots of
other work is going on, you may want to do your changes on a "side
branch" which will get merged into the main branch later on. Before
creating a branch, you discuss the matter with the other workers. If
you are new to CVS, you should read the CVS documentation several
times, and ask for help. The documentation is sufficiently large and
confusing that it is rather difficult to get right the first few
times.
<H2> <font color="turquoise">Adding Directories and Files</font></h2>
First create the new directories and files locally. Then, assuming
the new directory is named "newdir" and the new file is "newmod.c":
<pre><font color="yellow"> cvs add -m "New directory for ..." newdir
cd newdir
cvs add -m "File newmod.c is a module that ..." newmod.c
</font></pre>
<H2> <font color="turquoise">Deleting Directories and Files</font></h2>
You don't directly delete directories, you delete all the files in a
directory and the directory goes away during an "update -dP". To
delete one or more files:
<pre><font color="yellow"> cvs remove -f filename...
cvs commit -m 'deleted files because' filename...
</font></pre>
</body>
</html>