diff options
Diffstat (limited to 'HowToContributeToThisWiki.mdwn')
| -rw-r--r-- | HowToContributeToThisWiki.mdwn | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/HowToContributeToThisWiki.mdwn b/HowToContributeToThisWiki.mdwn new file mode 100644 index 00000000..cb3f3446 --- /dev/null +++ b/HowToContributeToThisWiki.mdwn @@ -0,0 +1,127 @@ +# How to Contribute to This Wiki + +(!) Some general hints first; they may sound very familiar from other software +projects: + +* Do independent changes *separately*: don't aggregate changes that don't + belong together. +* Install your changes *early* and *often*: don't hold your contribution back + until you think it is perfect. + + +## Edit Via the Web Interface + +When you found a page you want to work on, just follow the *Edit* link on the +top of the page. When doing this for the first time, this will first transfer +you to a page where you have to create a wiki account. After logging in, you +can edit the wiki pages. + + +## Working on a Checkout of the git Repository + +(!) What is being described here are only the basics. The checkouts are +completely valid git repositories and can (and want to) be treated as such. +Consult the git documentation about how to shuffle around with branches, how to +rename files, how to upload arbitrary data files, and so on. + + +First, let's make sure that you're properly identifying yourself towards git. + + $ git var GIT_AUTHOR_IDENT + Thomas Schwinge <tschwinge@gnu.org> 1186743435 +0200 + +If it doesn't look akin to that for you, you'd better adjust either your +*EMAIL* environment variable or alternatively tell git about your real +identity: + + $ git config --global user.name 'Your Name' + $ git config --global user.email you@somewhere.invalid + + +For being able to do a checkout from which you can later directly push your +changes back into the master repository, you need a +[[shell_account_on_*flubber*|Hurd/PublicHurdBoxen]]. (It's also very much +recommenable that you set up your local ssh configuration as advised on that +page.) If you have an account on there: + + $ git clone flubber:~wiki/wiki [dest] + +If you don't have such an account or don't have your login data handy, you can +still get the pages the read-only way. + +/!\ *Not yet available.* + + $ git clone git://flubber.bddebian.com/wiki [dest] + +If that also doesn't work out, you have yet another chance: pull over the http +protocol. Not very efficient (read: rather inefficient), but it works. This +is also read-only. + + $ git clone http://www.bddebian.com/git/wiki [dest] + +For all cases: if you omit *[dest]* it will default to *wiki*. + +Later, you can just *cd* into the *wiki* directory and run a *git pull* to get +hold of the latest changes others have been installing in the mean time. + + +But now: work on these files. + + $ cd wiki/ + $ emacs Hurd/NextHurd.mdwn + $ # Check what you've done. + $ git diff Hurd/NextHurd.mdwn + $ git commit Hurd/NextHurd.mdwn + [...] + $ # Add a new file. + $ emacs Hurd/DesignGoals.mdwn + $ git add Hurd/DesignGoals.mdwn + $ git commit Hurd/DesignGoals.mdwn + [...] + $ [...] + +Remember that at this stage your commits have only been installed into your +personal working copy. You'll finally have to explicitly install your changes +into the master repository, see below. + + +You can also locally get the whole wiki rendered to html pages: + + $ wiki/render_locally + [...] + scanning HowToContributeToThisWiki.mdwn + rendering HowToContributeToThisWiki.mdwn + + Now open `wiki.rendered/index.html' to browse the wiki pages. + + +If you like what you've done, then it's now time to publish your changes. + +If you can push directly into the master repository this is really simple: + + $ git push + updating 'refs/heads/master' + from d83f93f34b69633ca1afb588001df7addd708faf + to c0b8171de9c69e029bf998aafd4682105c217eb8 + Generating pack... + [...] + Updating web pages. This may up to a few minutes at the utmost... + +If you can't do that, then first prepare to publish your changes: + + $ git-format-patch -M -B origin + 0001-Be-a-bit-more-expressive.patch + [...] + +See through the generated **.patch* files and simply delete those you don't +want to pulish. + +Finally, publish the good ones. If you have a local mail transfer agent +running, the following is all you have to do: + + $ git-send-email --to web-hurd@gnu.org *.patch + [...] + +If you don't have an mta running, you'll have to find another way: either post +the **.patch* files to <web-hurd@gnu.org> or upload them somewhere for us to +download them from. |