Mercurial > mplayer.hg
changeset 18769:62455ce744c9
rename cvs-howto.txt to svn-howto.txt
| author | ivo |
|---|---|
| date | Wed, 21 Jun 2006 12:56:42 +0000 |
| parents | 023937301637 |
| children | b6225b75d0b0 |
| files | DOCS/tech/cvs-howto.txt DOCS/tech/svn-howto.txt |
| diffstat | 2 files changed, 343 insertions(+), 343 deletions(-) [+] |
line wrap: on
line diff
--- a/DOCS/tech/cvs-howto.txt Wed Jun 21 11:59:07 2006 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,343 +0,0 @@ - -About Subversion write access: -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before everything else, you should know how to use Subversion properly. -Subversion comes with some documentation. - - svn help - man svn - info svn - -are a good start. 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 are MPlayer specific guidelines. - - -I. TECH SIDE: -============= - -1. Checking out development source tree: - - svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ - -2. Updating source tree to latest revision: - - svn update - -3. Committing changes: - - svn update - svn commit --username USERNAME 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, 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. When - prompted for a password, type the password you got assigned by the Subversion - server admin. 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. - -4. Adding new files/directories: - - svn add filename/dirname - svn commit filename/dirname - -5. Removing files: - - svn delete filename - svn commit filename - -6. Checking changes: - - svn diff 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: - - 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/ - -8. Renaming/moving files or content 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 untraceable! - - 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. Checking status of source tree - - svn status - - This will detect all the changes you made and list what actions will be - taken in case of a commit (Additions, Modifications, Deletions, et cetera). - -11. 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. - -12. 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 admin <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 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.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/DOCS/tech/svn-howto.txt Wed Jun 21 12:56:42 2006 +0000 @@ -0,0 +1,343 @@ + +About Subversion write access: +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before everything else, you should know how to use Subversion properly. +Subversion comes with some documentation. + + svn help + man svn + info svn + +are a good start. 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 are MPlayer specific guidelines. + + +I. TECH SIDE: +============= + +1. Checking out development source tree: + + svn checkout svn://svn.mplayerhq.hu/mplayer/trunk/ + +2. Updating source tree to latest revision: + + svn update + +3. Committing changes: + + svn update + svn commit --username USERNAME 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, 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. When + prompted for a password, type the password you got assigned by the Subversion + server admin. 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. + +4. Adding new files/directories: + + svn add filename/dirname + svn commit filename/dirname + +5. Removing files: + + svn delete filename + svn commit filename + +6. Checking changes: + + svn diff 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: + + 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/ + +8. Renaming/moving files or content 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 untraceable! + + 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. Checking status of source tree + + svn status + + This will detect all the changes you made and list what actions will be + taken in case of a commit (Additions, Modifications, Deletions, et cetera). + +11. 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. + +12. 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 admin <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 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.