annotate DOCS/tech/svn-howto.txt @ 19248:dd30cb46819d

Add a paragraph about which Subversion version to use.

About Subversion write access:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Before everything else, you should know how to use Subversion properly.
Luckily Subversion comes with excellent documentation.

  svn help

shows you the available subcommands,

  svn help <command>

shows information about the subcommand <command>.

The most comprehensive manual is the book "Version Control with Subversion"
by Ben Collins-Sussman, Brian W. Fitzpatrick and C. Michael Pilato. It can
be viewed online at

http://svnbook.org/

For more information about the Subversion project, visit

http://subversion.tigris.org/

Consult these resources whenever you have problems, they are quite exhaustive.

What follows now is a basic introduction to Subversion and some MPlayer-specific
guidelines. Read it at least once, if you are granted commit privileges to the
MPlayer project you are expected to be familiar with these rules.



I. BASICS:
==========

0. Get Subversion:

  The MPlayer project server runs Subversion 1.2.3. For optimal compatibility
  you should use version 1.2.3 or later.


1. Checking out the source tree:

    svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ <target>

  This will put the MPlayer sources into the directory <target>.


2. Updating the source tree to the latest revision:

    svn update

  pulls in the latest changes from the repository to your working directory.


3. Adding/removing files/directories:

    svn add <filename/dirname>
    svn delete <filename/dirname>

  Subversion needs to get notified of all changes you make to your working
  directory.


4. Showing modifications:

    svn diff <filename(s)>

  will show all local modifications in your working directory as unified diff.


5. Inspecting the changelog:

    svn log <filename(s)>

  You may also find viewvc, a web frontend for Subversion, helpful. It's often
  more comfortable than using 'svn log' and 'svn diff'. Find it here:
  http://svn.mplayerhq.hu/mplayer/trunk/


6. Checking source tree status:

  svn status

  detects all the changes you made and lists what actions will be taken in case
  of a commit (additions, modifications, deletions, etc.).


7. Committing:

    svn update

  Run 'svn update' before committing to make sure there were no changes to the
  files you worked on in the meantime. Afterwards look at the output of

    svn diff <filename(s)>

  to doublecheck your changes before committing to avoid trouble later on. All
  experienced developers do this on each and every commit, no matter how small.
  Every one of them has been saved from looking like a fool by this many times.
  It's very easy for stray debug output or cosmetic modifications to slip in,
  please avoid problems through this extra level of scrutiny.

  Once you have made sure everything is fine

    svn commit <filename(s)>

  propagates your stuff to the repository. If you have made several independent
  changes, commit them separately, not at the same time.

  When prompted for a password, type the password you got assigned by the
  project admins. By default, Subversion caches all authentication tokens.
  This behaviour can be disabled by setting both 'store-passwords' and
  'store-auth-creds' to "no" in ~/.subversion/config. You might need to remove
  previous cache files, which are located in ~/.subversion/auth, by hand.

  You will be prompted for a log message in an editor, which is either specified
  by --editor-cmd on the command line, set in your personal configuration file
  (~/.subversion/config) or set by one of the following environment variables:
  SVN_EDITOR, VISUAL or EDITOR.

  Log messages should be concise but descriptive. Explain why you made a change,
  what you did will be obvious from the changes themselves most of the time.
  Saying just "bug fix" or "10l" is bad. Remember that people of varying skill
  levels look at and educate themselves while reading through your code. Don't
  include filenames in log messages, Subversion provides that information.


8. Renaming/moving files or contents of files:

  svn move <source> <destination>
  svn commit <source> <destination>

  Do not move or rename files before discussing it on the mplayer-dev-eng
  mailing list first!

  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 hard to trace.

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


9. Reverting broken commits

  There is no Subversion equivalent of the 'cvs admin -o' command. Instead,
  be very careful about what you commit! If somehow you broke something,
  revert the changes locally and re-commit with a proper commit message.
  You may want to use 'svn cat -r<revision> <filename>' to inspect an older
  revision.


10. Reverting local changes

  svn revert <filename(s)>

  In case you made a lot of local changes to a file and want to start over
  with a fresh checkout of that file, you can use 'svn revert <filename(s)>'.
  NOTE: This has nothing to do with reverting changes on the Subversion
  server! It only reverts changes that were not committed yet. If you need
  to revert a broken commit, see 9.


11. Changing commit messages

  svn propedit svn:log --revprop -r <revision>

  If your commit message is too short or not explanatory enough, you can edit
  it afterwards with 'svn propedit'.


Contact the project admins <root at mplayerhq dot hu> if you have technical
problems with the Subversion server.



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

1. You must not commit code which breaks MPlayer! (Meaning unfinished but
   enabled code which breaks compilation or compiles but does not work.)
   You can commit unfinished stuff (for testing etc), but it must be disabled
   (#ifdef etc) by default so it does not interfere with other developers'
   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. Do not commit unrelated changes together, split them into self-contained
   pieces.


4. Do not change behavior of the program (renaming options etc) or
   remove functionality from the code without approval in a discussion on
   the mplayer-dev-eng mailing list.


5. Do not commit changes to the build system (Makefiles, configure script)
   which change behaviour, defaults etc, without asking first. The same
   applies to compiler warning fixes, trivial looking fixes and to code
   maintained by other developers. We usually have a reason for doing things
   the way we do. Send your changes as patches to the mplayer-dev-eng mailing
   list, and if the code maintainers say OK, you may commit. This does not
   apply to files you wrote and/or maintain.


6. We refuse source indentation and other cosmetic changes if they are mixed
   with functional 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.) If you really need to make
   indentation changes (try to avoid this), separate them strictly from real
   changes.

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


7. Always fill out the commit log message. Describe in a few lines 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 unacceptable.


8. If you apply a patch by someone else, include the name and email address in
   the log message. Since the mplayer-cvslog mailing list is publicly
   archived you should add some spam protection to the email address. Send an
   answer to mplayer-dev-eng (or wherever you got the patch from) saying that
   you applied the patch. If the patch contains a documentation change, commit
   that as well; do not leave it to the documentation maintainers.


9. Do NOT commit to code actively maintained by others without permission. Send
   a patch to mplayer-dev-eng instead.


10. Subscribe to the mplayer-cvslog mailing list. The diffs of all 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.


11. Update the documentation if you change behavior or add features. If you are
    unsure how best to do this, send a patch to mplayer-docs, the documentation
    maintainers will review and commit your stuff.


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

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



III. Beginners Guide
====================

The typical flow of development would be:

1. Check out the source:

    svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ devel


2. Make your changes.


3. Create a patch:

  Run 'svn diff' from the root of the source tree, like this:

    cd devel
    svn diff > ../my_changes.patch

  If you have made several changes, but only want to submit one for review
  by other developers, you can specify the filename(s), for example:

    svn diff mplayer.c > ../major_cleanup.patch


4. Check the patch:

  Check out another, clean source tree and verify your patch:

    svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ clean
    cd clean
    patch -p0 --dry-run < ../my_changes.patch

  If there are no errors, you can apply your patch:

    patch -p0 < ../my_changes.patch

  After that, verify that MPlayer still builds correctly with your patch
  applied. Also, be sure that your patch meets our policy as described in
  section II, specifically rules 1 to 6, before you continue submitting
  the patch.


5. Submit the patch:

  Send an e-mail to the mplayer-dev-eng mailing list. Describe what your
  patch does and why, and attach the patch file for review by others.


6. During the review process, incorporate all suggested fixes. Go to step 2
  repeatedly until there is nothing more to do for step 6. Of course, if
  you don't agree with certain suggestions, things can be discussed on
  the mailing list in a polite manner.


7. Commit the patch:

  If your patch is accepted, double check if your source tree contains the
  most recent version of your patch with 'svn diff'! After verifying that
  you met these conditions, commit with:

    svn commit <filename(s)>

  Go to step 2 ad infinitum until MPlayer is the perfect media player ;)


Note: If you are listed as the maintainer for a particular piece of code,
you can skip step 5 and 6 if your patch _only_ applies to the code you
maintain. If it touches other code or is otherwise very intrusive, please
post it to mplayer-dev-eng first.