doc/tips/spam_and_softwaresites.mdwn

   1 [[!meta date="2010-03-01 13:14:48 +0000"]]
   2
   3 Any wiki with a form of web-editing enabled will have to deal with
   4 spam. (See the [[plugins/blogspam]] plugin for one defensive tool you
   5 can deploy).
   6
   7 If:
   8
   9  * you are using ikiwiki to manage the website for a [[examples/softwaresite]]
  10  * you allow web-based commits, to let people correct documentation, or report
  11    bugs, etc.
  12  * the documentation is stored in the same revision control repository as your
  13    software
  14
  15 It is undesirable to have your software's VCS history tainted by spam and spam
  16 clean-up commits. Here is one approach you can use to prevent this. This
  17 example is for the [[git]] version control system, but the principles should
  18 apply to others.
  19
  20 ## Isolate web commits to a specific branch
  21
  22 Create a separate branch to contain web-originated edits (named `doc` in this
  23 example):
  24
  25     $ git checkout -b doc
  26
  27 Adjust your setup file accordingly:
  28
  29     gitmaster_branch => 'doc',
  30
  31 ## merging good web commits into the master branch
  32
  33 You will want to periodically merge legitimate web-based commits back into
  34 your master branch. Ensure that there is no spam in the documentation
  35 branch. If there is, see 'erase spam from the commit history', below, first.
  36
  37 Once you are confident it's clean:
  38
  39     # ensure you are on the master branch
  40     $ git branch
  41       doc
  42     * master
  43     $ git merge --ff doc
  44
  45 ## removing spam
  46
  47 ### short term
  48
  49 In the short term, just revert the spammy commit.
  50
  51 If the spammy commit was the top-most:
  52
  53     $ git revert HEAD
  54
  55 This will clean the spam out of the files, but it will leave both the spam
  56 commit and the revert commit in the history.
  57
  58 ### erase spam from the commit history
  59
  60 Git allows you to rewrite your commit history.  We will take advantage of this
  61 to eradicate spam from the history of the doc branch.
  62
  63 This is a useful tool, but it is considered bad practise to rewrite the
  64 history of public repositories. If your software's repository is public, you
  65 should make it clear that the history of the `doc` branch in your repository
  66 is unstable.
  67
  68 Once you have been spammed, use `git rebase` to remove the spam commits from
  69 the history.  Assuming that your `doc` branch was split off from a branch
  70 called `master`:
  71
  72     # ensure you are on the doc branch
  73     $ git branch
  74     * doc
  75       master
  76     $ git rebase --interactive master
  77
  78 In your editor session, you will see a series of lines for each commit made to
  79 the `doc` branch since it was branched from `master` (or since the last merge
  80 back into `master`). Delete the lines corresponding to spammy commits, then
  81 save and exit your editor.
  82
  83 Caveat: if there are no commits you want to keep (i.e. all the commits since
  84 the last merge into master are either spam or spam reverts) then `git rebase`
  85 will abort. Therefore, this approach only works if you have at least one
  86 non-spam commit to the documentation since the last merge into `master`. For
  87 this reason, it's best to wait until you have at least one
  88 commit you want merged back into the main history before doing a rebase,
  89 and until then, tackle spam with reverts.