mirror of https://github.com/mpv-player/mpv
404 lines
14 KiB
Plaintext
404 lines
14 KiB
Plaintext
|
|
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.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. 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.
|
|
|
|
|
|
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.
|
|
|
|
|
|
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.
|