update HACKING notes for updating snapshots

Original commit message from CVS:
update HACKING notes for updating snapshots

1 files changed, 142 insertions, 24 deletions

diff --git a/HACKING b/HACKING
index 93f4dea..d4fafe1 100644
--- a/HACKING
+++ b/HACKING
@@ -42,6 +42,9 @@ What's more, if you want to be on the safe side, make sure that you can
 unapply and reapply without problems, by running quilt pop -a then
 quilt push -a.
 
+The ONLY exception to this is when you're working on a branch to update
+the upstream source you're working with.
+
 ***
 
 THE WAY
@@ -56,36 +59,140 @@ THE WAY
     NO files listed with question mark.  If there are, somebody before you
     probably made a mistake.  To manage the state correctly, it is vital that
     none of the files are unknown to CVS.
-  - if you want to add a file to a patchset, you need to:
-    - be in the right patchset
-    - quilt add (file)
-    - cvs add .pc/(patchsetname)/(file)
-    - cvs commit .pc/(patchsetname) (to update the state of quilt in cvs)
-    - edit the file
-    - cvs add the file if it doesn't exist yet
-    - quilt refresh
-    - quilt push -a (This one is IMPORTANT, otherwise you'll have a huge diff)
-    - cvs commit
-  - if you want to add a patchset, you need to:
-    - go over the procedure with thomas to check it's correct
-    - decide where in the stack to put it.  ask for help if you don't know.
-    - go there in the patch stack (use quilt pop/push)
-    - quilt new (patchsetname).patch (don't forget .patch !)
-    - quilt add (files)
-    - cvs add .pc/(patchsetname) the whole tree
-    - cvs commit .pc/(patchsetname)
-    - quilt refresh
-    - quilt push -a
-    - cvs commit
-    - cvs diff (to check if any of the files are unknown to CVS; if they are,
-      you need to add them to CVS)
+
+
+- if you want to add a file to a patchset, you need to:
+  - be in the right patchset
+  - quilt add (file)
+  - cvs add .pc/(patchsetname)/(file)
+  - cvs commit .pc/(patchsetname) (to update the state of quilt in cvs)
+  - edit the file
+  - cvs add the file if it doesn't exist yet
+  - quilt refresh
+  - quilt push -a (This one is IMPORTANT, otherwise you'll have a huge diff)
+  - cvs commit
+
+- if you want to add a patchset, you need to:
+  - go over the procedure with thomas to check it's correct
+  - decide where in the stack to put it.  ask for help if you don't know.
+  - go there in the patch stack (use quilt pop/push)
+  - quilt new (patchsetname).patch (don't forget .patch !)
+  - quilt add (files)
+  - cvs add .pc/(patchsetname) the whole tree
+  - cvs commit .pc/(patchsetname)
+  - quilt refresh
+  - quilt push -a
+  - cvs commit
+  - cvs diff (to check if any of the files are unknown to CVS; if they are,
+    you need to add them to CVS)
+
+THE UPSTREAM
+------------
+At some points you want to update the upstream snapshot code to a newer date.
+This is easy if you follow the steps outlined here, but make sure to follow
+them correctly !
+
+- find a good CVS snapshot date for upstream, one that is known to work.
+  You're going to save yourself quite a bit of trouble if you verify this
+  first !
+- check it out to a local directory:
+  cvs -z9 -d:pserver:anonymous@mplayerhq.hu:/cvsroot/ffmpeg export -D '2004-04-11 23:00 GMT' ffmpeg
+- compile it and test it, make sure it works
+
+- in gst-ffmpeg/gst-libs/ext/ffmpeg:
+  - Pre-flight checks:
+    - first make sure you don't have local changes, all files are either in
+      CVS or in .cvsignore patch, the whole quilt stack is applied, and stuff
+      works.
+    - do a quilt pop -a and quilt push -a to verify everything is ok.
+
+  - Branch and rollback:
+    - tag HEAD with the branch root point:
+      cvs tag BRANCH-UPDATE-CVS-2004-04-11-23-00-ROOT
+    - branch:
+      cvs tag -b BRANCH-UPDATE-CVS-2004-04-11-23-00
+    - FIXME: lock cvs HEAD
+    - update local copy to branch:
+      cvs update -r BRANCH-UPDATE-CVS-2004-04-11-23-00
+    - peel off all patches:
+      quilt pop -a
+    - commit this
+      cvs commit
+    - check
+      cvs diff
+      you should only have ? for files that are generated somehow (binaries,
+      build files, ...)
+      you get warnings about cvs not finding files to diff that are in .pc
+      or generated by your patches
+
+  
+    - if you want, you can now compare this state of CVS (which should 
+      be last upstream CVS combined with your local unapplied quilt state)
+    - remember to NOT do cvs update from here on, since you popped your quilt
+      state all your added files that are also in CVS are not locally present.
+
+  - sync with upstream:
+    - in a temp dir, redo the export:
+      cd ..
+      mkdir tmp
+      cd tmp
+      cvs -z9 -d:pserver:anonymous@mplayerhq.hu:/cvsroot/ffmpeg export -D '2004-04-11 23:00 GMT' ffmpeg
+    - rsync it over the old ffmpeg tree
+      rsync -arv ffmpeg ..
+    - go back and commit this new snapshot
+      cd ../ffmpeg
+      cvs commit
+    - check if any new files got added that you should add to cvs
+      cvs diff
+      This will list a lot of local files missing, from your quilt state,
+      which you shouldn't worry about.  Just inspect all the ?'s and add
+      files to cvs that belong to upstream and should be in cvs.
+    - if everything's ok and commited, tag the state:
+      cvs tag UPSTREAM-CVS-2004-04-11-23-00
+
+  - reapply and fix quilt patches one by one
+    - try applying one
+      quilt push
+    - if that didn't work, inspect the patch and figure out how to fix it:
+      - if the patch got applied upstream completely, quilt push will tell
+        you the patch looks like a reverse patch.  In that case you can
+        remove the patch from your patches file (patches/series), and
+        remove the .pc/$(patchname) and patches/$(patchname).patch files from
+        cvs.
+      - if the patch conflicts somehow, you can force application with
+        quilt push -f
+        and then resolve all the rejects, and fix the patch completely.
+        Then refresh quilt state with 
+        quilt refresh
+     - when the patch is succesfully removed or reworked, commit current state
+       to CVS, then check again if nothing is missing using cvs diff, and
+       resolve problems/apply missing files from your quilt state/...
+
+  - after reapplying your complete quilt state, test locally if the complete
+    gst-ffmpeg module now works.  Compile and test.  Resolve all problems
+    (upstream errors, missing symbols, missing files, ...) until you have
+    a working module.  commit again.
+
+  - merge to head:
+    - update locally back to head
+      cvs update -A
+    - FIXME: unlock cvs HEAD
+    - merge from your branch
+      cvs update -j BRANCH-UPDATE-CVS-2004-04-11-23-00
+    - commit
+      cvs commit
+    - check for diffs
+      cvs diff
+    - tag merge point
+      cvs tag BRANCH-UPDATE-CVS-2004-04-11-23-00-MERGE
+
+  - get a drink
 
 THE PLUGIN
 ----------
 Some notes on how ffmpeg wrapping inside GStreamer currently works:
 * gstffmpeg{dec,enc,demux,mux}.c are wrappers for specific element types from
     their ffmpeg counterpart. If you want to wrap a new type of element in
-    ffmpeg (e.g. the URLProtocol things), then you'd need to write a new
     wrapper file.
 
 * gstffmpegcolorspace.c is a wrapper for one specific function in ffmpeg:
@@ -144,3 +251,14 @@ Some notes on how ffmpeg wrapping inside GStreamer currently works:
 
 * there's lots of things that still need doing. See the TODO file for more
     information.
+
+THE REMINDERS
+-------------
+* the initial ffmpeg checkout was imported using:
+  - get CVS ffmpeg
+    cvs -z3 -d:pserver:anonymous@mplayerhq.hu:/cvsroot/ffmpeg co -D '2004-03-09 06:00 GMT' ffmpeg
+
+  - delete all CVS directories
+    find . -name CVS -type d -exec rm -rf {} \;
+  - import it in our CVS
+    cvs -d:ext:thomasvs@cvs.freedesktop.org:/cvs/gstreamer import -m "Import of FFmpeg cvs from 2004-03-09 06:00 GMT" mirror/ffmpeg FFMPEG CVS-2004-03-09