GNU Hurd wiki/ contributing/ wiki

(!) Some general hints first; they may sound very familiar from other software projects:

Before doing any changes, you are encouraged to play a bit in this wiki's sandbox, to become familiar with the Markdown syntax. Get some help on formatting.

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.".

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.

Every page on the site is editable. Feel free to join in, but we do have some simple requests. In an ideal wiki, everyone is equal and shares equal rights, liberties, responsibilities and common sense. Please try to match the tone of your topics and edits with the existing topics. If we all pull in the same direction the site will be more useful for everyone, especially for our own use.

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.

(!) Before attempting any bigger editing work (to which you are sincerely invited!) be sure to check the involved pages' Discussion subpages (linked from the pages' header line) and in there take down (short) notes about the editing endeavors you're going to undertake. Doing so should help to (a) avoid double work and (b) avoid merge conflict if you install your changes into the main repository.

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 and need to be a member of the wiki group. (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.

Getting the files by using the native git protocol is currently not possible, but will be possible again as soon as the master repository has been relocated to the GNU Savannah machine.

$ 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. (Even better would be to do a git fetch, followed by a git rebase origin/master to avoid those Merge branch ... messages. See the git documentation for details.)

But now: work on these files.

$ cd wiki/
$ 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.

You can also locally get the whole wiki rendered to html pages:

$ wiki/render_locally
[...]
scanning contributing/wiki.mdwn
rendering contributing/wiki.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 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.