docs: add Edward's git plugin moving howto to moving-plugins document

diff --git a/docs/random/moving-plugins b/docs/random/moving-plugins
index e994cac..b1cc88f 100644 (file)
--- a/docs/random/moving-plugins
+++ b/docs/random/moving-plugins
@@ -1,10 +1,15 @@
 Moving around plug-ins between source modules
 ---------------------------------------------
 
-Last updated: 2006-09-01
+Last updated: 2009-08-11
 
-How to get your plug-in out of -bad and into -good or -ugly
------------------------------------------------------------
+Contents:
+  1. How to get your plug-in out of -bad and into -good or -ugly (ie. policies)
+  2. How to move plugins between modules with git (ie. technical howto)
+
+==============================================================
+1. How to get your plug-in out of -bad and into -good or -ugly
+==============================================================
 
 Since GStreamer 0.9.x, we have four plugin modules: -base, -good, -ugly,
 and -bad.  Plug-ins are by default added to -bad.  They can only move
@@ -141,3 +146,69 @@ CHECKLIST
   - see gstreamer/docs/README; section on adding plugins and elements
   - "make update" in docs/plugins and commit the new file
   - edit -docs.sgml and add an include for the file
+
+
+============================================
+2. Moving plugins with GIT (technical howto)
+============================================
+
+Let's say we are moving the 'weneedthis' plugins from -bad/gst/weneedthis/ to
+-good.
+
+We want to end up with the following situation after the plugin move:
+
+* weneedthis is no longer usable/visible in HEAD of -bad
+* weneedthis is present and usable in HEAD of -good
+* The whole history of commits concerning weneedthis are visible in -good
+* The whole history of commits concerning weneedthis are visible in -bad
+* If we go back to the previous release commit for -good, the 'weneedthis'
+  plugin code and commit history are not visible.
+* If we go back to the previous release commit for -bad, the 'weneedthis'
+  plugin code and commits are visible.
+
+
+# Four steps for moving plugins
+----------
+
+For this, we use git-format-patch which will extract the various commits
+involving the plugin we want to move into individual numbered patches.
+
+> cd gst-plugins-bad.git/
+> git format-patch -o ../patches/ --subject-prefix="MOVED FROM BAD" start..HEAD -- gst/weneedthis/ tests/check/elements/weneedthis.c
+or (without the prefix)
+> git format-patch -o ../patches/ --no-numbered --subject-prefix='' start..HEAD -- gst/weneedthis/ tests/check/elements/weneedthis.c
+
+We can then take those patches and commit them into -good.
+For safety, it is recommended to do all this work in a temporary branch
+
+> cd ../gst-plugins-good.git/
+> git checkout -b moving-weneedthis
+> git am -k ../patches/*.patch
+
+At this point, we have all the commits related to gst/weneedthis/ in -bad.
+
+We also need to move the other related parts in:
+* configure.ac
+* Makefile.am from intermediary directories (if needed)
+* i18n
+* documentation
+
+All those modifications should be committed as one commit with an obvious
+summary:
+"Moved 'weneedthis' from -bad to -good"
+> git commit -v -m "Moved 'weneedthis' from -bad to -good" <modified files>
+
+We can now merge the branch into master and push it out for everybody.
+
+> git checkout master
+> git merge moving-weneedthis
+
+The last step is to remove the plugin from the original module:
+
+> git rm gst/weneedthis/
+
+Remove all the code that was moved from configure, makefiles, documentations,
+and commit that with the *SAME* commit message as the last commit we did in
+-good:
+> git commit -v -m "Moved 'weneedthis' from -bad to -good" <modified files>
+