devel/GitWiki.mdwn

   1 # Using git to edit the OpenAFS wiki
   2
   3 Unlike most wiki engines, which generate html from database records, the wiki
   4 engine on the OpenAFS wiki site generates static html files from a set of
   5 source files in markdown format. Revision history of the pages is managed with
   6 git. The OpenAFS gerrit system has been configured to accept git pushes to
   7 update the wiki, which means it is now possible to update this site using git
   8 directly.
   9
  10 This page describes how to use git to create and edit pages on this wiki as an
  11 alternative to the online web form. A local wiki setup is described to allow
  12 you to preview changes before pushing them to the public wiki. One advantage to
  13 this approach is that you can edit while offline and then submit your work
  14 later, as you would for any other git based project. Using git for making
  15 changes is especially handy when making a series of changes which should be
  16 committed together, such as reorganizing pages and links.
  17
  18 ## Prerequisites
  19
  20 Read [[GitDevelopers]] before following the instructions on this page.
  21
  22 The following are needed to be able to edit the wiki pages with git.
  23
  24 * `git` is installed and configured with your name and email.
  25 * an OpenAFS gerrit account; see [[registering with gerrit|GitDevelopers]] for details.
  26
  27 A installation of the `ikiwiki` software on your laptop or workstation is
  28 recommended but is optional. This will allow you preview your changes before
  29 submitting them to the OpenAFS wiki. The `ikiwiki` requires:
  30
  31 * [[ikiwiki|http://ikiwiki.info]] installation
  32 * a basic ikiwiki setup file (shown below)
  33 * a basic httpd setup
  34
  35 ## Getting the wiki source pages
  36
  37 Use `git clone` to get the openafs-wiki source files from the
  38 `gerrit.openafs.org` repo.
  39
  40     git clone ssh://gerrit.openafs.org/openafs-wiki.git
  41
  42 Set up your OpenSSH configuration to connect to the gerrit server port as
  43 described in [[GitDevelopers]].  The commit hook which generates a gerrit
  44 'change id' as described in [[GitDevelopers]] is *not required* for pushing
  45 openafs-wiki changes to gerrit.
  46
  47 Note: At this time, the git.openafs.org repo (gitweb) can trail the canonical
  48 repo on gerrit.openafs.org, since changes made through the web interface are
  49 not automatically propagated to the openafs gitweb. This means that if you want
  50 to make changes by pulling and pushing via git, you must pull from the
  51 gerrit.openafs.org repository above. If you pull from git.openafs.org,
  52 subsequent pushing may fail.
  53
  54 ## Editing pages
  55
  56 When you are satisfied with your changes, use `git add` and `git commit` to
  57 create a commit to be submitted. To publish your changes on the wiki, push your
  58 commits *directly* to the **master** branch `master`. Do **not**
  59 push to the gerrit review branch `refs/for/master`.
  60
  61     git push origin master
  62
  63 The commit will be merged immediately to the openafs-wiki.git repository.  The
  64 html on the wiki server will be automatically updated after a successful `git
  65 push` after a few moments.  The changes will not be held by gerrit for review.
  66
  67 ## Setting up ikiwiki to preview your changes
  68
  69 This is an optional but recommended step. The ikiwiki software can be installed
  70 on your local machine so you can preview your changes before publishing them on
  71 the wiki.  The default ikiwiki installation instructions are intended for a
  72 server setup.  A simplified, minimal setup is shown here.
  73
  74 First, install the ikiwiki package for your system.  Use `apt` to install
  75 ikiwiki on a Debian or Ubuntu system.
  76
  77     sudo apt-get install ikiwiki
  78
  79 See [[ikiwiki downloads|http://ikiwiki.info/download]] for installation
  80 instructions for other platforms.
  81
  82 Create a minimal ikiwiki configuration file by saving the following in
  83 the file '~/openafs-wiki.setup',  where `<username>` is your username:
  84
  85     use IkiWiki::Setup::Standard {
  86         wikiname => 'openafs-wiki',
  87         srcdir => '/home/<username>/openafs-wiki',
  88         destdir => '/home/<username>/public_html/openafs-wiki',
  89         url => 'http://localhost/openafs-wiki/',
  90         rcs => '',
  91         usedirs => 1,
  92             add_plugins => [qw{goodstuff}],
  93     }
  94
  95 The 'srcdir' should reference your local openafs-wiki git repository, created
  96 by the git clone. The 'destdir' will be created by ikiwiki when the pages are
  97 generated for preview. The 'destdir' may be set to a DocumentRoot directory if
  98 you have a local http server to show the pages.
  99
 100 Note the 'rcs' setting is intentionally left empty in this setup.
 101
 102 The html files can now be generated from the openafs-wiki source by 'ikiwiki'.
 103 Run the following command to create the 'destdir' directory and create the
 104 static html files in that directory:
 105
 106     ikiwiki --setup ~/openafs-wiki.setup
 107
 108 Install a httpd server, such as apache.  Configure the document root to be the
 109 same as the `destdir` path in the `openafs-wiki.setup` file.
 110
 111 The pages may be previewed locally by pointing your browser at:
 112
 113     http://localhost/
 114
 115 Run the following `ikiwiki` command to regenerate the html files from the
 116 source files after making any changes to the source files.
 117
 118     ikiwiki --setup ~/openafs-wiki.setup --refresh