Merge branch 'master' into external_pager_mechanism

Conflicts:
	microkernel/mach/external_pager_mechanism.mdwn

5 files changed, 460 insertions, 0 deletions

diff --git a/contributing/questionnaire.mdwn b/contributing/questionnaire.mdwn
new file mode 100644
index 00000000..bc548b64
--- /dev/null
+++ b/contributing/questionnaire.mdwn
@@ -0,0 +1,45 @@
+[[!meta copyright="Copyright © 2006, 2007, 2008 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled
+[[GNU Free Documentation License|/fdl]]."]]"""]]
+
+People often come to us and state that they'd like to help with the GNU/Hurd.
+This is very good and very much encouraged: we're always looking for volunteers
+to help with the effort!  However, for things to eventually become productive,
+we'd like every new potential contributor to read through the following list of
+items and spend some time thinking about those.
+
+
+* What areas are you interested in contributing to?
+
+    Think a moment about this list: porting and extending existing software to
+    run on Hurd systems; work on existing or write new Hurd servers or
+    libraries; work on the standard C library; make Hurd stuff usuable from
+    other programming languages than C; work on the current Mach microkernel;
+    do research and development of a next-generation microkernel; help with
+    development of new Hurd libraries and servers on top of that.  Those
+    projects are all within the *Hurd* topic, but are vastly different
+    projects.
+
+* How is your expertise about system and kernel programming?
+
+    Sadly we don't have the ressources to teach you from ground-up.  We will --
+    of course! -- try to give answers to specific questions, but on substantial
+    parts of your contribution you'll have to work on your own.  (Unless there
+    is someone who is already working in the same area, of course.)
+
+* Have you previously been working on Free Software projects?
+
+    Are you used to the working-style Free Software projects bring with them?
+    Did you already contribute to other projects?  What sort of contributions?
+
+* What is your motivation to work on the GNU Hurd?
+
+
+Every new contributor is very much encouraged to take some notes about these
+items and post them to *[[mailing lists/bug-hurd]]*.
diff --git a/contributing/web_pages.mdwn b/contributing/web_pages.mdwn
new file mode 100644
index 00000000..51ce873e
--- /dev/null
+++ b/contributing/web_pages.mdwn
@@ -0,0 +1,230 @@
+[[!meta copyright="Copyright © 2007, 2008, 2009, 2010 Free Software Foundation,
+Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled
+[[GNU Free Documentation License|/fdl]]."]]"""]]
+
+[[!meta title="Contribute to the Web Pages"]]
+
+[[!toc levels=3]]
+
+
+# General Information
+
+(!) 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.
+
+## Syntax
+
+Before doing any changes, you are encouraged to play a bit in the
+[[sandbox]], to become familiar with the [[ikiwiki/Markdown]] syntax.  Get some
+[[help_on_formatting|ikiwiki/formatting]].
+
+## Commit Messages
+
+Please comment every change you make, however small.  Keep all comments short
+and to the point, e.g. "Fixed typo." or "Added link to main page.".
+
+## Asking Questions -- on Sub-Pages
+
+Feel free to ask questions or report problems on every page's [[discussion]]
+sub-page.  They're reachable from the *Discussion* link on the top of the page,
+which will, when selected, create a new page if there isn't one yet.
+
+## Editing Pages
+
+Every page on the site is editable, like in a wiki.  Feel free to join in, but
+we do have some simple requests.  Please try to match the *tone* of your topics
+and edits with the existing topics.  If we all pull in the same direction these
+pages will be more useful for everyone, especially for our own use.
+
+### News Items
+
+There are [[more detailed instructions about editing news items|news]].
+
+<a name="staging_area">
+## Staging Area
+</a>
+
+When you commit changes, either using the web interface or checking them in
+into the repository; they won't become visible on
+<http://www.gnu.org/software/hurd/> immediately, but on
+<http://www.bddebian.com:8888/~hurd-web/> instead.  The former set of pages,
+the official GNU Hurd web appearance, will be updated periodically (but
+manually) from the latter one, where every edit is visible immediately.  This
+is so that we have a chance to have the pages make fit for appearance on
+`www.gnu.org`, but you are nevertheless able to work on all pages
+unrestrictedly.
+
+
+# Editing via the Web Interface
+
+When you have found a page you want to work on, just follow the *Edit* link at the
+top of the page.  When doing this for the first time, this will first redirect
+you to a page where you will have to create an account.  After logging in, you
+can edit pages.
+
+
+# Working on a Checkout of the Git Repository
+
+(!) What is being described here is 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 add arbitrary data files, and so on.
+
+(!) Before attempting any bigger editing work (to which you are sincerely
+invited!) be sure to check the involved pages' *Discussion* sub-pages (linked
+from the pages' header line) and in there take down (short) notes about the
+editing endeavours you're going to undertake.  Doing so should help to (a) avoid
+double work and (b) avoid merge conflicts if you install your changes into the
+main repository.
+
+## Identifying Yourself
+
+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
+
+## Getting the Sources
+
+To be 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*|public_hurd_boxen]] and need to be a member of
+the *hurd-web* group.  (It's also recommended that you set up your local
+SSH configuration as advised on that page.)  If you have an account on there:
+
+    $ git clone flubber:~hurd-web/hurd-web [dest]
+
+If you don't have such an account or don't have your login data handy, you can
+still get pages the read-only way.
+
+    $ git clone git://flubber.bddebian.com/~hurd-web/hurd-web [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:8888/git/hurd-web [dest]
+
+For all cases: if you omit `[dest]` it will default to `hurd-web`.
+
+Later, you can just `cd` into the `hurd-web` directory and run a `git pull` to
+get hold of the latest changes others have been installing in the mean time.
+(In most cases, you should use `git pull --rebase`,
+to avoid useless *Merge branch ...* messages.  See the
+Git documentation for details.)
+
+## Editing the Content
+
+But now: work on these files.
+
+    $ cd hurd-web/
+    $ emacs hurd/ng.mdwn
+    $ # Check what you've done.
+    $ git diff hurd/ng.mdwn
+    $ git commit hurd/ng.mdwn
+    [...]
+    $ # Add a new file.
+    $ emacs microkernel/mach/issues.mdwn
+    $ git add microkernel/mach/issues.mdwn
+    $ git commit microkernel/mach/issues.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.
+
+## Preview Changes
+
+You can also locally get the whole set of pages rendered to HTML:
+
+    $ hurd-web/render_locally
+    [...]
+    scanning contributing/web_pages.mdwn
+    rendering contributing/web_pages.mdwn
+    
+    Now open `hurd-web.rendered/index.html' to browse the pages.
+
+### ikiwiki's `w3mmode`
+
+If you're a [`w3m`](http://w3m.sourceforge.net/) user, you can also use `w3m`
+to edit your files locally, as it were done through the web interface at
+<http://www.bddebian.com:8888/~hurd-web/>.
+
+First, generate the wrapper.  Unless the configuration is changed, this has to
+be done only once.
+
+    $ hurd-web/render_locally --w3m-wrapper
+    successfully generated /home/thomas/.ikiwiki/wrappers/hurd-web.cgi
+
+Render the pages:
+
+    $ hurd-web/render_locally --w3m
+    [...]
+    scanning contributing/web_pages.mdwn
+    rendering contributing/web_pages.mdwn
+    
+    Now open `hurd-web.rendered.w3m/index.html' to browse the pages.
+
+Invoke `w3m`:
+
+    $ w3m hurd-web.rendered.w3m/index.html
+
+Or, to directly create a new page:
+
+    $ w3m 'file:///$LIB/ikiwiki-w3m.cgi/hurd-web.cgi?page=open_issues/gnumach_has_a_bug&do=create'
+
+Note that the changes you do via `w3m` will not be committed to the VCS (see
+[[render_locally]] for details.)
+
+## Publish Your Changes
+
+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 publish.
+
+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.
diff --git a/contributing/web_pages/news.mdwn b/contributing/web_pages/news.mdwn
new file mode 100644
index 00000000..a700c3ad
--- /dev/null
+++ b/contributing/web_pages/news.mdwn
@@ -0,0 +1,110 @@
+[[!meta copyright="Copyright © 2009, 2010 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+[[!meta title="""How to prepare and publish "a month of the Hurd" for the last
+month"""]]
+
+We prepare *a month of the Hurd* in a public git branch (`master-news_next`),
+and merge that one into `master` once we want to publish the news.  The idea is
+to record to-be-published changes on that branch at they time they arise, and
+then publish them en bloc at the end of the month.
+
+As this is done on a separate branch, there are two options: you can have
+separate repositories (*clones*, or *checkouts*; what you get from `git clone`)
+for the `master` and `master-news_next` branches, or you can deal with both in
+the same repository.  Having separate repositories you don't have to remember
+which branch you're on, and don't have to switch between branches before
+beginning to edit files, and it doesn't matter -- as no switching between
+branches is needed -- if you have uncomitted changes to some files.  On the
+other hand, you may want to keep it all in one repository, to save disk space,
+and for shuffling different branches' commits being (a bit) easier.
+
+For practical work that means to use the following commands: 
+
+  * create a local branch for `master-news_next`
+
+        $ git fetch
+        $ git checkout -b master-news_next origin/master-news_next
+
+      * if you already have created a local branch `master-news_next`: update to
+        the latest version of it
+
+            $ git checkout master-news_next
+            $ git pull --rebase
+
+  * edit
+
+    Always do check which branch you're on (asterisk in the first column of
+    `git branch`'s output), and only then begin to do your changes and commit
+    them.
+
+    We should not update news items that have already been published (that is,
+    on <http://www.gnu.org/software/hurd/news.html>; no problem for the
+    [[staging area|web_pages#staging_area]]), as the system will always also
+    update the RSS feeds, etc., causing the old news item to reappear on feeds,
+    which is a bit of a nuisance.
+
+      * at the beginning of a month: create a new news entry
+
+            $ cp contributing/web_pages/news/skeleton.mdwn news/YYYY-MM.mdwn
+            $ # edit the new file, then add the changes in git
+            $ git add news/YYYY-MM.mdwn
+            $ git commit -m "Begun the news entry for YYYY-MM."
+
+        That is, use the [[news skeleton|skeleton]] as a template for the new
+        news snippet.  It also includes a list of the places to watch for news.
+
+  * check the outgoing changes
+
+        $ git log --reverse -p -C origin/master-news_next..master-news_next
+
+  * push the changes
+
+        $ git push origin master-news_next
+
+      * if push fails, pull and rebase the local changes on top of the remote
+        changes
+
+            $ git pull --rebase
+
+        This will only happen if someone else has been installing commits into
+        `origin`'s `master-news_next` branch since the last time you
+        synchronized to it.
+
+        Note that this might cause some conflicts to arise -- if the remote
+        repository contains commits that conflict with any that you've been
+        recording in your local repository.  For this reason, you might want to
+        already do this *rebase* before beginning you local edits, simply to
+        shorten the time frame in which such conflicts can arise.
+        (Theoretically, in the very rare case of very much concurrent editing
+        going on, you'd have to repeat this again (and again...) before
+        succeeding to push your changes.)
+
+  * at the end of the month: prepare for publishing the news
+
+    Edit the news entry's *meta date* value to the timestamp when the news
+    entry is [[published|news]].  We have to set that one manually, as
+    otherwise the timestamp of the news entry file's creation will be taken,
+    which is (much) earlier, and not what we want.  We do not set the *meta
+    updated* value, as it's correct to update that one upon further
+    modifications of the news entries.
+
+  * ... and publish
+
+        $ git checkout master
+        $ git pull --rebase
+        $ git merge master-news_next
+        $ git push origin master
+
+    That means, for publishing we merge `master-news_next` into `master`.
+    After that merge, work for the next month's news item can continue on
+    `master-news_next`.
+
+    Arne Babenhauserheide uses a [[merge-news]] script for doing this.
diff --git a/contributing/web_pages/news/merge-news b/contributing/web_pages/news/merge-news
new file mode 100644
index 00000000..33c01b7b
--- /dev/null
+++ b/contributing/web_pages/news/merge-news
@@ -0,0 +1,13 @@
+#!/bin/sh
+
+# merge into master  
+git checkout master  
+git pull --rebase  
+git merge master-news_next
+
+# push master  
+git push origin master
+
+# switch back to master-news_next  
+git checkout master-news_next  
+git pull --rebase
diff --git a/contributing/web_pages/news/skeleton.mdwn b/contributing/web_pages/news/skeleton.mdwn
new file mode 100644
index 00000000..8f08fba2
--- /dev/null
+++ b/contributing/web_pages/news/skeleton.mdwn
@@ -0,0 +1,62 @@
+[[!meta copyright="Copyright © 2010 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+<!-- Date when the news item is (to be) pulished (important for RSS feeds).
+Will be set by tschwinge when publishing.
+[[!meta date="YYYY-MM-DD HH:MM UTC"]]
+-->
+
+A month of the Hurd: *TODO* / *TODO* / *TODO*.
+[[!if test="included()" then="""[[!toggle id=full_news
+text="Details."]][[!toggleable id=full_news text="[[!paste id=full_news]]"]]"""
+else="
+[[!paste id=full_news]]"]]
+
+[[!cut id="full_news" text="""
+
+Watch these places for news:
+
+  * GNU
+
+      * <http://lists.gnu.org/archive/html/bug-hurd/YYYY-MM/threads.html>
+
+      * <http://lists.gnu.org/archive/html/commit-hurd/YYYY-MM/threads.html>
+
+      * <http://lists.gnu.org/archive/html/help-hurd/YYYY-MM/threads.html>
+
+      * <http://lists.gnu.org/archive/html/web-hurd/YYYY-MM/threads.html>
+
+      * <http://lists.gnu.org/archive/html/hurd-devel/YYYY-MM/threads.html>
+
+      * <http://sourceware.org/ml/libc-alpha/YYYY-MM/>
+
+        Also Git log.
+
+      * (<http://sourceware.org/ml/libc-hacker/YYYY-MM/>)
+
+      * (<http://sourceware.org/ml/glibc-cvs/YYYY-qQ/>)
+
+        Better use the Git log.
+
+  * Debian
+
+      * <http://lists.debian.org/debian-hurd/YYYY/MM/>
+
+      * <http://lists.debian.org/debian-glibc/YYYY/MM/>
+
+  * Arch Hurd
+
+      * <http://www.archhurd.org/news.php>
+
+      * <http://planet.archhurd.org/>
+
+      * (<http://lists.archhurd.org/devel/maillist.html>)
+
+"""]]