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.apache.org/
Consult these resources whenever you have problems, they are quite exhaustive.
You do not need a special checkout that works through ssh or similar in order
to be able to commit changes. All you need is the username and password pair
that you received from the MPlayer Subversion server admin.
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.5. For optimal compatibility
you should use version 1.5 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.
For cosmetics-only commits you should get (almost) empty output from
svn diff -x -uwb <filename(s)>
Also check the output of
svn status
to make sure you did not forget to 'svn add' some files (they will be marked
with '?').
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 behavior 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/copying files or contents of files:
svn move/copy <source> <destination>
svn commit <source> <destination>
Do not move, rename or copy files of which you are not the maintainer without
discussing it on the mplayer-dev-eng mailing list first!
Never copy or move a file by using 'svn delete' and 'svn add'. Always use
'svn move' or 'svn copy' instead in order to preserve history and minimize
the size of diffs.
To split a file, use 'svn copy' and remove the unneeded lines from each file.
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 are 2 ways to reverse a change, they differ significantly in what they
do to the repository.
The recommit old method:
svn merge
svn ci <file>
This simply changes the file(s) back to their old version locally and then
the change is committed as if it were a new change.
The svn copy method
svn rm <file>
svn cp -r<good revision> svn://svn.mplayerhq.hu/mplayer/trunk/[<path>/]<file> <file>
svn ci <file>
This simply removes the file and then copies the last good version with
its history over it. This method can only be used to revert the n last
commits but not to revert a bad commit in the middle of its history.
Neither method will change the history, checking out an old version will
always return exactly that revision with all its bugs and features. The
difference is that with the svn copy method the broken commit will not be
part of the directly visible history of the revisions after the reversal
So if the change was completely broken like reindenting a file against the
maintainers decision, or a change which mixed functional and cosmetic
changes then it is better if it is not part of the visible history as it
would make it hard to read, review and would also break svn annotate.
For the example of a change which mixed functional and cosmetic parts they
should of course be committed again after the reversal but separately, so one
change with the functional stuff and one with the cosmetics.
OTOH if the change which you want to reverse was simply buggy but not
totally broken then it should be reversed with svn merge as otherwise
the fact that the change was bad would be hidden.
One method to decide which reversal method is best is to ask yourself
if there is any value in seeing the whole bad change and its removal
in SVN vs. just seeing a comment that says what has been reversed while
the actual change does not clutter the immediately visible history and
svn annotate.
If you are even just slightly uncertain how to revert something then ask on
the mplayer-dev-eng mailing list.
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, but not smaller. Do not split commits by files or directories,
keep related changes together.
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 which change behavior, 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. Do not mix cosmetic changes (indentation, function / variable renaming and
similar) with functional changes in a single commit. Instead, commit such
changes as a separate commit of their own.
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.
12. Always send a patch to the mplayer-dev-eng mailing list before committing
if you suspect that the change is going to be controversial. Based on past
experience, these changes are likely to be controversial:
- feature removal, even if obsolete
- changes to "special" output messages (like the "Core dumped ;)" message)
- verbosity changes from default (info) level
- changes to "historical" parts of docs and web pages
- use of internal or external libraries
- reverting commits from other developers
- making the spelling of words consistent without actually correcting
any spelling errors.
13. Try to keep important discussions and requests (also) on the mplayer-dev-eng
mailing list, so that all developers can benefit from them.
IRC is good for quick discussions, but nobody is there 24/7.
14. MPlayer contains some external code that is partly patched, partly copied
verbatim (see Copyright for details). This code should not be modified
unless there is a very good reason. Much of it is maintained upstream.
We should be good open source citizens, submit our fixes upstream and keep
the differences as small as possible.
If you have to modify external code, do not forget to update the diff file
with our local changes.
15. Use K&R style with 4 space indentation, no tabs and no trailing whitespace.
Unnecessary braces should be avoided. This policy applies to new files. In
existing files that don't follow K&R style, try to respect the surrounding
style, but in doubt, go for K&R.
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.
