add hacking notes

Original commit message from CVS:
add hacking notes

1 files changed, 54 insertions, 21 deletions

diff --git a/HACKING b/HACKING
index 97cadaa..40c14d2 100644
--- a/HACKING
+++ b/HACKING
@@ -1,3 +1,5 @@
+THE GOAL
+--------
 What we are trying to achieve:
 
 satisfy:
@@ -8,32 +10,63 @@ satisfy:
     make distcheck
     non-srcdir build (ie, mkdir build; cd build; ../configure; make)
 
-How it works:
+THE SETUP
+---------
+There is a "mirror" root CVS module that contains "ffmpeg".
+This directory contains a vendor-branch checkout of upstream FFmpeg CVS
+of a given day.
 
-* configure checks whether or not it should update ffmpeg from CVS by looking
-  at the nano version number
-  - if it's 1, we're in cvs mode, and it should check it out
-  - if it's not 1, we're in prerel or rel mode, and the code should already
-    be on disk
-    FIXME: we could change this to really check out the source code if some
-    required files aren't there just in case someone checks out from CVS
-    but CVS is not at nano 1
+On head, the following things have been commited on top of this:
+* patches/, which is a directory with a set of patches, and a series file
+  listing the order, as generated by quilt
+* .pc/, which is a tree of files that quilt uses to keep control of its state.
+  It contains a list of applied patches, and one directory per patch,
+  containing a tree of hardlinked files that were added to the patchset, and
+  a .pc file listing all files part of the patchset.
+* the result of having all these patches commited (ie, quilt push -a) to the
+  ffmpeg tree.
 
-* patching of the checked-out copy happens at
+Both the actually patched CVS ffmpeg code as well as the .pc dir need to be
+commited to CVS so the state of quilt wrt. the source is in sync.
 
-Axioms under which we work:
-- the dist tarball needs to include either
-  - the pristine ffmpeg checkout + our patches + a patch mechanism on make
-  or
-  - the ffmpeg checkout with patches already applied
+THE WAY
+-------
 
-- configure/make is not allowed to touch files that already live in the source
-  tree; if they need to then they need to be copied first and cleaned
-  afterward
-
-- it would be very nice if, on update of either the Tag file or the patch set,
-  make would know exactly what to do with it.
+- If you want to hack on our copy of the FFmpeg code, there are some basic
+  rules you need to respect:
+  - you need to use quilt.  If you don't use quilt, you can't hack on it.
+  - we separate patches based on the functionality they patch, and whether
+    or not we want to send stuff upstream.  Make sure you work in the right
+    patch.  use "quilt applied" to check which patches are applied.
+  - before starting to hack, run cvs diff.  There should be NO diffs, and
+    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
+    - 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 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