annotate DOCS/tech/cvs-howto.txt @ 13108:a7ff30cf339f

spelling, rewording, some additions

About CVS write access:
~~~~~~~~~~~~~~~~~~~~~~~

Before everything else, you should know how to use CVS properly. CVS comes with
some documentation, as usual

  cvs --help
  man cvs

are a good start. The most comprehensive manual is the book "Version Management
with CVS" by Per Cederqvist. It may be available on your system via

  info cvs

or online at

  http://www.cvshome.org/docs/manual/

Another very good resource is "The CVS Book - Open Source Development with CVS"
by Karl Fogel and Moshe Bar. It is also available online:

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

Consult these resources whenever you have problems, they are quite exhaustive.
What follows now are MPlayer specific guidelines.


I. TECH SIDE:
=============

1. Changing password:

  As you probably got a restricted CVS-only shell, it's not trivial:

    ssh [e-mail] passwd

  Replace LOGIN with your login name. Leave 'passwd' unchanged, it's a command.

  Note: If you need a real shell for something, tell A'rpi.

2. Checking out development source tree:

    export CVS_RSH=ssh
    cvs -z3 -d:ext:[e-mail]:/cvsroot/mplayer co -P main

  Replace LOGIN with your login name.
  NOTE: cvs -d:pserver: mode doesn't allow writing, even with password!

3. Committing changes:

    cvs -z3 commit -m "comment - what you changed and why" filename(s)

  Do not use comments such as: "bug fix." or "files changed" or "dunno".
  You don't have to include the filename in the comment, as comments are linked
  to files. If you have made several independent changes, commit them
  separately, not at the same time. If you leave out -m at the command line you
  will be prompted for a comment in an editor (usually vi).

4. Adding new files/dirs:

    cvs add filename/dirname

5. Removing files:

    rm filename
    cvs remove filename
    cvs commit -m "reason for removing this file" filename

6. Checking changes:

    cvs -z3 diff -u filename(s)

  It's recommended to check changes before committing. especially if you forget
  what you changed :)
  This way you will see if your patch has debug stuff or indentation changes
  and you can fix it before committing and triggering me to use cvs-backup.

7. Checking changelog:

    cvs -z3 log filename(s)

8. Renaming/moving files or content of files, removing empty directories:

  You CANNOT do that. Ask the CVS server admin (A'rpi) to do it!
  Do NOT remove & re-add a file - it will kill the changelog!!!!

  Don't do a lot of cut'n'paste from one file to another without a very good
  reason and discuss it on the mplayer-dev-eng mailing list first. It will make
  those changes untraceable!

  Such actions are useless and treated as cosmetics in 99% of cases,
  so try to avoid them.

9. Reverting broken commits

  In case you committed something really broken and wish to undo it completely,
  you can use the 'cvs admin -o' command, which removes entries from the
  revision history of a file. For the corner case that you remove the last
  revision this amounts to reverting a commit.

  Assuming that 1.123 is the last revision

    cvs -z3 admin -o1.123 filename

  will remove revision 1.123, thus reverting the file back to revision 1.122.

  ONLY use this command to delete the LAST revision of a file. Removing other
  revisions will NOT undo the changes from that revision in the last revision
  and leave holes in the revision history.


Contact A'rpi <[e-mail]> if you have technical problems with the CVS
server.



II. POLICY / RULES:
===================

1. You shouldn't commit code which breaks MPlayer! (Meaning unfinished but
   enabled code which breaks compilation or compiles but does not work.)

2. You don't have to over-test things. If it works for you, and you think it
   should work for others, too, then commit. If your code has problems
   (portability, exploits compiler bugs, unusual environment etc) they will be
   reported and eventually fixed.

3. You can commit unfinished stuff (for testing etc), but it must be disabled
   (#ifdef etc) by default.

4. Do not change behavior of the program (renaming options etc) without
   discussing it first at the mplayer-dev-eng mailing list. Do not remove
   functionality from the code. Just improve!
   Do not commit changes to the build system (Makefiles, configure script)
   which change behaviour, defaults etc, without asking (and your change being
   accepted) on the mplayer-dev-eng mailing list first. The same applies to
   compiler warning fixes and trivial looking fixes. We usually have a reason
   for doing things the way we do. Send them as patches to the mailing list,
   and if the code maintainers say OK, you may commit. This does not apply to
   files written and/or maintained by you.

5. We refuse source indentation and other cosmetic changes, such commits will
   be rejected and removed. Every developer has his own indentation style, you
   should not change it. Of course if you (re)write something, you can use your
   own style... (Many projects force a given indentation style - we don't.)

   NOTE: If you had to put if(){ .. } over a large (> 5 lines) chunk of code,
   do NOT change the indentation of the inner part (move it right)!

6. Always fill out the comment at committing (-m switch of CVS, or in the
   editor if you left out -m). Describe in a few lines (usually one line is
   enough) what you changed and why. You can refer to mailing list postings if
   you fix a particular bug. Comments such as "fixed!" or "Changed it." are not
   acceptable.

7. If you apply a patch by someone else, include his name and email address in
   the CVS comment! Do NOT commit patches for other developer's code (code not
   maintained by you) without his permission! If he didn't commit - he probably
   has a reason! Send an answer to mplayer-dev-eng (or wherever you got the
   patch from) saying that you applied it.

8. A'rpi developed something called cvs-backup. It archives the CVS repository
   after each commit - so commits can be reversed (without messing up the
   changelog) if they are bad. If you think your bug fix or other change was
   bad and unneeded, ask A'rpi to reverse it instead of committing the previous
   version!

9. You will have write access to DOCS/. This used to be different to avoid
   breaking docs or getting translations or the homepage desynced. If you are
   unsure about this, send a patch to mplayer-dev-eng or even better to
   mplayer-docs, the documentation maintainers will review and commit your
   stuff.

10. Subscribe to the mplayer-cvslog mailing list. The diffs of all CVS commits
    are sent there and reviewed by all the other developers. Bugs and possible
    improvements or general questions regarding commits are discussed there. We
    expect you to react if problems with your code are uncovered.

Also read DOCS/tech/patches.txt !!!!

We think our rules are not too hard. If you have comments, contact us.



III. Beginners Guide	by David Holm
====================

When I first got CVS write access I got banned after only a few hours
because I didn't fully understand this documentation. This part is for
those of you who have just got CVS write access and want to avoid the
most common pitfalls leading to CVS ban.
I will introduce a step-by-step guide explaining how I'm making sure
that my CVS commits are proper and won't get me banned.

1. You should set up two directoress for MPlayer, one which contains the stable
   version and has the :ext: option instead of :pserver: in CVS/Root.
   The other should be your development directory and have the CVS/Root set to
   :pserver: instead of :ext:, that way you can't commit development code
   by accident (since only :ext: allows writes).
   This is my setup:
   ~/mplayer
	    /main
	    /main.dev
    NOTE: I'll use these directory names from here on in the guide, what you
    call your directories is entirely up to you. This is _only_ an example.

2. When you are satisfied with the changes in "main.dev" and think you are
   ready to commit the changes to CVS start by doing the following in the
   "~/mplayer" dir":
   diff -Nur -x "CVS" -x ".*" main main.dev > dev2stable
   dev2stable is the filename for the patchfile, it doesn't matter what you
   call it.

3. Now comes one of the tricky parts, editing the patch. I prefer using mcedit
   (comes with Midnight Commander) since it does syntax highlighting in patches
   (= it uses colors to identify lines =), But most ASCII editors should do
   (meaning don't use Star Office and save it as a Star Office document for
   instance ;) I will try to explain this as good as I can.

   Read through the patch and remove all occurrences of:

     * diff -Nur.... that are affecting files YOU have NOT modified. These
       occur when either main or main.dev are a different version (not checked
       out at the same time)
       EVERYTHING from the diff -Nur... line until the next diff -Nur... line
       are changes to the file specified after the diff options, and ONLY that
       file.

     * Lines containing "Binary files..." if you add the 'a' switch to -N(a)ur
       binary files will be added to the patch as well, making it huge and
       putting a lot of unnecessary data in it (since you seldom commit any
       binaries).

     * If you find changes within a diff block that you don't want to commit
       you can delete them if they are the only changes ranging from the
       @@ -x,y +x,y @@ until the line before the next @@ -x,y +x,y @@. You
       _cannot_ remove single lines after a @@ -x,y +x,y @@ because that will
       break the patch!.
       Example:
         ...
         @@ -15,34 +15,6 @@
         - old_option;
         + new_option;
         @@ -65,13 +65,3 @@
         ...

         OK:
         ...
         @@ -65,13 +65,3 @@
         ...

         Will break patch:
         ...
         @@ -15,34 +15,6 @@
           old_option;
         @@ -65,13 +65,3 @@
         ...

       When I end up in a situation where I have to remove just some lines from
       a block, I leave it alone, remember (write down) which file it is in and
       then edit the file in "main" after I've applied the patch.

     * Now it's time for applying the patch to the "main" (stable) directory.
       This should be done in two steps:
         1. enter "main" and run

               patch -p1 --dry-run < ../dev2stable

 	    -p1 means that you are one level deep (that you have entered the
            "main" directory and that should be stripped when patching, if you
            run it from "~/mplayer" you would use -p0).
 	    --dry-run means that patch does everything it normally does but
            without modifying ANY files. This is a great way of testing whether
            your patch works or not.
 	    "../dev2stable" is your patchfile. (don't forget the '<')
 	    If the dry run fails, check the line it failed on and figure out
            why it failed, make a new patch and try again.

 	2. OK, you finally have a working patch, remove --dry-run, patch "main"
           and you are done with the patching part =).

4. It's almost time for the final step, committing the changes. But first you
   MUST make sure your changes compile without breaking anything and that it
   follows the Policy mentioned in section 2. (Read it until your eyes are
   bleeding if you want to keep CVS access!)
   Don't worry about object files etc that will be created in your "main" dir,
   they won't  be sent to CVS on a commit, you must use the add command to add
   new files (discuss it on dev-eng before adding new files!).
   Now to make sure your additions follow policy do the following on every file
   you will commit:

     cvs -z3 diff -u <filename> > <filename.d>

   Of course the output file (<filename.d>) can have any name you want. This
   will create a file showing the differences between the file on CVS and your
   updated local file.
   I will explain some of the policy rules I had a hard time understanding:

     II.5: This means that if for instance you have lines in <filename.d> that
           look something like this:

             -
             +

           That means you have added or removed tabs or spaces on that line.
           That qualifies as a cosmetic change and is disallowed. Edit the
           file and put back/remove the added/removed tabs/spaces.
           Rediff the file and make sure the cosmetic changes are fixed.

     II.6: Make sure you read and understand this properly before committing
           anything. Commit one file at a time!

5. OK, you have a working patch following the CVS policy, excellent work. Now
   for the final step, committing. This is really simple. Just run the
   following command in "main" for each file you want to commit:

     cvs -z3 commit -m "<comment (changes)>" <filename>
     cvs -z3 commit <filename>

   The latter will bring up your default text editor for writing comments (I
   prefer this method).

You are done, congratulations. If you are certain you have followed all of the
policy you shouldn't have any trouble with the CVS maintainers at all.
At first I thought the policy was too strict, but I discussed it with A'rpi and
he made some very good points, so don't complain.