Add a PKG_NOTES file in Riece
authorSteve Youngs <steve@sxemacs.org>
Tue, 28 Jun 2016 07:54:58 +0000 (17:54 +1000)
committerSteve Youngs <steve@sxemacs.org>
Tue, 28 Jun 2016 07:54:58 +0000 (17:54 +1000)
Signed-off-by: Steve Youngs <steve@sxemacs.org>
xemacs-packages/riece/PKG_NOTES [new file with mode: 0644]

diff --git a/xemacs-packages/riece/PKG_NOTES b/xemacs-packages/riece/PKG_NOTES
new file mode 100644 (file)
index 0000000..5079de3
--- /dev/null
@@ -0,0 +1,128 @@
+-*- mode: text -*-
+
+These notes are only relevant if you are planning to hack this package
+or sync it with the package's upstream.
+
+This package was imported into the SXEmacs packages repository as a
+"subtree".  Most people, most of the time, will never need to know or
+care about that.  For all intents and purposes the fact that it came
+in as a subtree will be completely invisible.  It is only when you
+want to sync up with the external upstream repo that you need to care
+for a couple of things, as set out below...
+
+---[Pre-Requisites]-----------------------------------------------------
+First up, a couple of additions to your git config, if you haven't
+already done so:
+
+Staying out of conflict hell:
+
+       git config rerere.enabled true
+       git config rerere.autoupdate true
+
+git-rerere is something that is so handy that you'd probably want to
+turn it on globally, so perhaps add '--global' to those commands
+above.  You won't regret it.
+
+Needed custom merge driver:
+
+       git config merge.sxepkg.driver true
+
+For the packages that have come into our repo as a subtree there are
+often files that we don't ever want overwritten or changed when we pull
+in updates from upstream.  It is usually things like '.gitignore' or
+'Makefile'.  Instead of dealing with conflicts, or having to manually
+check and re-edit, we use a custom merge driver that makes git believe
+that a successful merge has happened so no changes need to be applied
+to the local file.
+
+The first half of achieving that is what the above command sets up.
+Please note, the config entry 'merge.sxepkg.driver' is not a bool.
+The 'true' refers to the command true(1), often /bin/true, or a shell
+built-in. 
+
+The other half of the magic is in '.gitattributes' in the toplevel of
+our repo.  It'll have entries like...
+
+    xemacs-packages/gnus/.gitignore merge=sxepkg
+    xemacs-packages/riece/.gitignore merge=sxepkg
+
+
+Add the upstream repo as a remote:
+
+       git remote add riece git://git.savannah.nongnu.org/riece.git
+       git config remote.riece.tagOpt --no-tags
+
+
+---[Updating]-----------------------------------------------------------
+OK, so you want to sync up our Riece package with the upstream, here
+is what you do...
+
+It is safest to do this from our repo's toplevel directory so that is
+what the first command here does, puts you in the right directory...
+
+     cd $(git rev-parse --show-toplevel) &&
+     git checkout -b pkgsync &&
+     git fetch riece &&
+     git merge -X subtree=xemacs-packages/riece --squash riece/master
+
+Notice that the merge command is using '--squash', so nothing has been
+committed yet.  You can now look over the changes (git-status,
+git-diff, etc), test build, make any needed tweaks or changes that the
+sync may have caused, or whatever else you may need to do to get the
+updated package playing nice with our packages.
+
+Once you have it all ready you'd follow pretty much the same steps as
+you would when submitting patches/contributions to SXEmacs itself.
+See:
+
+       (Info-goto-node "(sppm)Patches")
+
+Note that is SXEmacs specific, not package specific, so please apply
+common sense while reading it.  The SPPM will be updated shortly for
+packages. 
+
+Please note, and this is REALLY IMPORTANT, if you make changes to this
+package that should be sent upstream, you MUST put those changes into
+their own self-contained separate commits.  The reason for that is so
+we can cherry-pick them out and send them upstream.
+
+
+---[Pkg-Specific Quirks]------------------------------------------------
+Riece uses something called "gnulib" in a git submodule for autoconf
+related auxilary things, and for generating version strings.  We
+haven't included that submodule in our packages repo, and never will.
+Consequently Riece's version strings don't get updated automatically
+when you sync with upstream.
+
+Here is how to update them manually:
+
+  1) Create a branch that tracks the Riece remote master branch
+
+     git checkout -b myriece riece/master
+
+  2) Fetch the tags
+
+     git fetch --tags
+
+  3) git describe will now give you the version info, for example...
+
+     git describe
+     => v9.0.0-21-gcf23226
+
+     From that example, the version string would be: '9.0.0.21-cf23'
+
+  4) Kill the tags because we don't want them polluting up our repo
+
+     git tag -d $(git tag)
+
+  5) Jump back to the branch where you're doing the sync/update and
+     update the version string in the following places...
+
+     xemacs-packages/riece/doc/version-en.texi
+     xemacs-packages/riece/doc/version-ja.texi
+     xemacs-packages/riece/lisp/riece-package-info.el
+     xemacs-packages/riece/Makefile
+
+  6) You can now nuke that 'myriece' branch if you want.
+
+------------------------------------------------------------------------