GNU Hurd/ contributing/ Contribute to the Web Pages

Welcome to... ... the GNU Hurd!

  1. General Information
    1. Syntax
    2. Commit Messages
    3. Asking Questions -- on Sub-Pages
    4. Editing Pages
      1. Which Pages to Work on?
      2. News Items
    5. Staging Area
  2. Editing via the Web Interface
  3. Working on a Checkout of the Git Repository
    1. Ikiwiki Installation
      1. Debian Wheezy
    2. Identifying Yourself
    3. Getting the Sources
    4. Editing the Content
    5. Preview Changes
      1. ikiwiki's w3mmode
    6. Publish Your Changes
  4. New Year Procedure

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 Markdown syntax. Get some help on 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.

Which Pages to Work on?

If you don't know which pages to work on, please have a look at those tagged with open issue documentation. Typically, you'll have to look at the pages' source code (Markdown) to see which parts the tag applies to.

News Items

There are more detailed instructions about editing news items.

Staging Area

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 https://darnassus.sceen.net/~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.

Ikiwiki Installation

You'll want to install ikiwiki in order to locally render the pages you're editing.

Debian Wheezy

$ apt-get install ikiwiki libyaml-syck-perl markdown libsearch-xapian-perl texinfo

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 darnassus 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 darnassus:~hurd-web/hurd-web.git [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, see the Clone URLs given on https://darnassus.sceen.net/cgit/hurd-web.git:

$ git clone git://darnassus.sceen.net/hurd-web.git [dest]

..., or:

$ git clone https://darnassus.sceen.net/cgit/hurd-web.git [dest]

Or, you can check out the Savannah repository:

$ git clone git://git.savannah.gnu.org/hurd/web.git [dest]

..., or:

$ git clone https://git.savannah.gnu.org/cgit/hurd/web.git [dest]

See https://git.savannah.gnu.org/cgit/hurd/web.git. If you're using the ssh protocol, and you're a member of the Hurd's Savannah group, you can also push to this repository. The disadvantage of pushing to the Savannah repository is that there is no ikiwiki installation where the pushed changes are immediatelly rendered and viewable by everyone.

For all cases: if you omit [dest] it will default to hurd-web for the darnassus repository, or web for a Savannah clone.

Later, you can just cd into the hurd-web or web directory, and, for example, run git pull to get hold of the latest changes others have been installing in the mean time.

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 user, you can also use w3m to edit your files locally, as it were done through the web interface at https://darnassus.sceen.net/~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.

New Year Procedure

Files to update:

  • /config_edittemplate/*.mdwn, /.templates/autotag.tmpl
  • /contributing/web_pages/news/skeleton.mdwn
  • /copyright.mdwn