path: root/contributing.mdwn

[[!meta copyright="Copyright © 2006, 2007, 2008, 2009, 2010, 2011 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]]."]]"""]]

[[!tag stable_URL]]

So, you are interested in contributing to the GNU Hurd project?  Welcome!
Every single contribution is very much encouraged.

There are various ways to contribute; read up on contributing to...

[[!toc levels=3]]

If someone of you is lurking around here and would like to contribute, but
feels she / he could do so better under formal mentoring: please
[[contact_us]], or just speak up at one of the [[regular IRC
meetings|IRC#regular_meetings]]!

We also have a list of [[open_issues]] and one for more elaborate [[project
ideas|community/gsoc/project_ideas]] - the latter originally written for the
[[Google Summer of Code|community/gsoc]], but not exclusively.  Even just
investigating open issues, without being able to fix them, can be useful,
because a issue that has been tracked down often becomes obvious to address for
people who know the stuff -- but these people typically don't have the time
that is needed to track down the issues.


# Documentation


## Technical Writer

Our hackers (programmers) typically do what their kind always does: they code.
What they don't like too much is documenting their wonderful achievements.  On
the other hand, there are people (you?) who enjoy documenting technical
matters, so don't hesitate to [[contact_us]] if technical documentation shall
be your contribution to GNU Hurd development.


## Web Pages

Please read about [[how_to_contribute_to_these_web_pages|web_pages]].


<a name="hurd_on_mach"></a>
# Improve GNU Hurd Running on GNU Mach

The *[[GNU Hurd|hurd]] running on the [[GNU Mach
microkernel|microkernel/mach/gnumach]]* is what is commonly meant when people
are talking about GNU/Hurd systems.

This system has mostly been designed and implemented
[[in the '90s|history]].  It works and is usable.
For example, these web pages have been rendered on a GNU/Hurd system.

You can try it out for yourself: for getting access, installing
[[Debian_GNU/Hurd|hurd/running/debian]] will probably be the easiest and most
feature-complete solution.  If you don't have spare hardware to use for doing
so, you can also get a
[[shell_account_on_a_public_Hurd_machine|public_hurd_boxen]].  Depending on the
things you're going to work on (and on your internet connection), this may be
an easy way of getting used to Hurd systems.  Installing in a virtual machine
is another possibility, see the page about
[[running_a_Hurd_system|hurd/running]] for the full story.
In particular, running a Debian GNU/Hurd [[QEMU image|hurd/running/QEMU]] may
be a viable alternative.

Then you can either play around and eventually strive to do something
useful or -- if you want -- [[ask_us|contact_us]] to assign something to you, depending
on the skills you have and the resources you intend to invest.

Please spend some time with thinking about the items in this [[questionnaire]].

Before you can significantly contribute to the operating system itself, you'll
need to take some time to learn about the system, for example:
[[microkernels for beginners|microkernel/for_beginners]], [[Mach's
concepts|microkernel/mach/concepts]], [[Hurd's concepts|hurd/concepts]], the
*[[hurd/critique]]*.  Until you can understand and do the basic exercises
listed there, you won't be able to significantly contribute to the Hurd.

For more reading resources, please see these web pages, for example,
[[Hurd_documentation|hurd/documentation]] and
[[Mach_documentation|microkernel/mach/documentation]] for links to a bunch of
documents.


<a name="porting"></a>
## Porting Packages

Debian is currently the Hurd distribution of choice among Hurd users and
developers.

Here is a
[[list_of_Debian_packages_that_need_porting|hurd/running/debian/porting]].

You can also just [[install_Debian_GNU/Hurd|hurd/running/debian]] and find what
doesn't work or suit you and try to improve that.

You can also have a look at the [List of failing packages](http://people.debian.org/~sthibault/failed_packages.txt).

For guidelines, please have a look at the dedicated [[porting_page|hurd/porting]].


## Open Issues

There is a list of [[open_issues]].  This list includes everything from bug
reports to open-ended research questions.


<a name="insta-dev-env"></a>
## Instant Development Environment

<!-- I don't like this being here.  At least not in this form.  This just
duplicates information that is available in other places.  (Or should be
available in other places, in more elaborate form.)

The idea of a one-stop development environment is not bad (I like that), but
I'd do this differently.  For example, we should add some Git submodules to the
master hurd.git repository (which is currently empty), to branches that are
known to build and interface correctly with current GNU/Hurd system
installations (thus including TLS, etc.), and also add in my cross-gnu scripts
and a simple build machinery so this is usable from GNU/Linux (and other
systems), and so on and so forth.

I'll have to think about it some more.

--[[tschwinge]].  -->

*This is a very brief guide to get your development environment set up. Pester ArneBab @ irc.freenode.net on IRC if something does not work :)*
([[!taglink open_issue_documentation]])

* Install qemu-kvm via your distros packages.
* Download the [qemu image](http://people.debian.org/~sthibault/hurd-i386/debian-hurd.img.tar.gz): `wget http://people.debian.org/~sthibault/hurd-i386/debian-hurd.img.tar.gz`
* Unpack it: `tar xf debian-hurd.img.tar.gz`
* Run it: `qemu-kvm debian-hurd.img -m 512 -no-kvm-irqchip` # …irq… is a currently necessary fix due to some changes in Linux. Optionally use `--curses` to keep your keyboard layout. If need be modprobe kvm_amd, kvm intel and kvm to get kvm support (which is much, much faster)
* login as root
* `apt-get update`
* `apt-get install -y git mercurial emacs vim`
* `apt-get build-dep -y hurd gnumach`
* `git clone git://git.sv.gnu.org/hurd/hurd.git`
* `git clone git://git.sv.gnu.org/hurd/gnumach.git`
* `git clone git://git.sv.gnu.org/hurd/incubator.git`
* Get more from the [repo list](http://git.savannah.gnu.org/cgit/hurd/).
* Read the docs on these pages.
* Start hacking.
* For shutting down, use `reboot`, then press `c` in grub and issue halt (to avoid filesystem corruption). Adding `--no-reboot` to the qemu line should help, too.


<a name="hurd_on_modern_microkernel"></a>
# Design / Research: GNU Hurd on a Modern Microkernel

Developers [[have_identified|hurd/critique]] a number of problem with the *Hurd on
Mach* system.  Problems, that can not easily be fixed by bug-fixing the
existing code base, but which require design changes -- deep going ones
actually.

As such systems (as the desired one) are not in common use, but are -- if at
all -- research projects, this new *Hurd on a modern microkernel* project
itself is more a research project than a *sit down and implement/code/hack*
project.

If you're interested in contributing in this area, knowing the *Hurd on Mach*
system (see [[above|contributing#hurd_on_mach]]) nevertheless is a
prerequisite.  At least have a deep look at the documentation pointers.  Also
read through the [[HurdNG|hurd/ng]] section.

Please send email to the [[mailing lists/l4-hurd]] mailing list for discussing
this post-Mach system design.


# Final Words -- Difficulties

Please note that doing substantial contributions to a project as big and as
encompassing as the GNU Hurd is not a trivial task.  For working on the GNU
Hurd's inner guts and getting useful work done, you have to plan for a
many-months learning experience which will need sufficient self-motivation.
Working on an advanced operating system kernel isn't something you can do in a
few free minutes -- even less so without any previous [[kernel]] hacking
experience.

Likewise, the Linux kernel maintainers are stating the exactly same
difficulties, which is well presented by Jonathan Corbet in his 2010 Linux
Kernel Summit report for the opening sessions about [*welcoming of
newcomers*](http://lwn.net/Articles/412639/).

But of course, none of this is meant to be dismissive, or to scare you away --
on the contrary: just [[start
using|hurd/running]] the GNU Hurd, and either notice yourself what's not
working as expected, or have a look at one of the [[Open Issues]], and we shall
see if you'll evolve to be the next core Hurd hacker!
You'll *just* have to get excited about it!