mirror of https://github.com/mpv-player/mpv
350 lines
14 KiB
Plaintext
350 lines
14 KiB
Plaintext
|
|
About Subversion 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 LOGIN@mplayerhq.hu passwd
|
|
|
|
Replace LOGIN with your login name. Leave 'passwd' unchanged, it's a command.
|
|
|
|
2. Checking out development source tree:
|
|
|
|
export CVS_RSH=ssh
|
|
cvs -z3 -d:ext:LOGIN@mplayerhq.hu:/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 update -dPA
|
|
cvs -z3 commit 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. You will be prompted for a comment in an
|
|
editor (see 'cvs -e', usually vi).
|
|
|
|
4. Adding new files/dirs:
|
|
|
|
cvs add filename/dirname
|
|
cvs commit filename
|
|
|
|
Directories are added immediately, no commit necessary. Make sure you do not
|
|
wrongly commit non-executable files with execute permissions set as this has
|
|
to be fixed manually in the repository. Binary files must be added with
|
|
'cvs add -kb'.
|
|
|
|
5. Removing files:
|
|
|
|
rm filename
|
|
cvs remove filename
|
|
cvs commit filename
|
|
|
|
6. Checking changes:
|
|
|
|
cvs -z3 diff -u filename(s)
|
|
|
|
Doublecheck your changes before committing to avoid trouble later on.
|
|
This way you will see if your patch has debug stuff or indentation
|
|
changes and you can fix it before committing and triggering flames.
|
|
|
|
7. Checking changelog:
|
|
|
|
cvs -z3 log filename(s)
|
|
cvs -z3 annotate filename(s)
|
|
|
|
You may also find viewcvs, a web frontend for CVS helpful. It's often more
|
|
comfortable than using cvs log, cvs annotate and cvs diff. Find it here:
|
|
http://www.mplayerhq.hu/cgi-bin/cvsweb.cgi/main
|
|
|
|
8. Renaming/moving files or content of files, removing empty directories:
|
|
|
|
You CANNOT do that. Ask the CVS server admin to do it!
|
|
Do NOT remove & readd 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
|
|
|
|
Should you commit something really broken, notice it quickly and wish to undo
|
|
it completely, the 'cvs admin -o' command can be used as a last resort. This
|
|
command removes entries from the revision history of a file. For the corner
|
|
case of removing the last revision (and only then!) this amounts to reverting
|
|
a commit. The HEAD version is not affected by removing revisions that came
|
|
before, only revision history will be lost and holes left in the revision
|
|
numbering. ONLY EVER use this command to delete the LAST revision of a file.
|
|
|
|
In short, if you use this improperly you can wreak permanent havoc. Employ it
|
|
only if you are completely sure of what you are doing.
|
|
|
|
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.
|
|
|
|
10. RSA authentication
|
|
|
|
Since mplayerhq.hu uses ssh.com and not OpenSSH you will have to convert your
|
|
OpenSSH RSA keys to IETF SECSH format with
|
|
|
|
ssh-keygen -e
|
|
|
|
if you want to use RSA authentication. See ssh(1) and ssh-keygen(1) for
|
|
details.
|
|
|
|
|
|
Contact the project admin <root at mplayerhq dot hu> if you have technical
|
|
problems with the CVS 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 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.
|