RepoMirrors
/
mpv
mirror of https://github.com/mpv-player/mpv
1
0
Fork 0
Code Issues Releases Wiki Activity
mpv/DOCS/tech/cvs-howto.txt

358 lines
14 KiB
Plaintext
Raw Blame History

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 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 CVS 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 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.
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. Revert a commit ONLY in case of a big blunder like committing something not
intended to be committed or committing a wrong file, the wrong version of a
patch, cosmetics or broken code and you are going to recommit the right
thing immediately.
Never revert changes made a long time ago or buggy code. Fix it in the
normal way instead.
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.
Reference in New Issue View Git Blame Copy Permalink