From adb16ca16208c4f8e28546e65ddefadd12634fec Mon Sep 17 00:00:00 2001 From: Edward Hervey Date: Tue, 11 Aug 2009 02:54:55 +0100 Subject: [PATCH] docs: add Edward's git plugin moving howto to moving-plugins document --- docs/random/moving-plugins | 77 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 74 insertions(+), 3 deletions(-) diff --git a/docs/random/moving-plugins b/docs/random/moving-plugins index e994cac..b1cc88f 100644 --- 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" + +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" + -- 2.7.4