Jan. I've just written a little draft to help you with the website.
The draft includes some suggestions about index, and some sections like
"getting started" (how to download, test, and install Hurd, putting Debian
GNU/Hurd as example), and "how to contribute", with some tips about how to
write code (follow the coding style), and how to generate a patch.
I expect this draft can be useful for your work.
El jue., 20 ago. 2020 a las 23:24, Jan Wielkiewicz (<
tona_kosmicznego_smie...@interia.pl>) escribió:
> Dnia 2020-08-20, o godz. 18:06:02
> Richard Braun <rbr...@sceen.net> napisał(a):
>
> > On Thu, Aug 20, 2020 at 03:19:56PM +0200, Almudena Garcia wrote:
> > > But, about the website, if I remember well, this thread started
> > > because of an offer to update the website.
> > > Why don't we accept the offer?
> > >
> > > It's a bad idea to reject this type of offer only for prejudices
> > > about the attractive.
> >
> > The help was not refused. Samuel actually said it's all fine after
> > clarifying a few things.
> >
> > > As I told before, I know many people who reject Hurd after showing
> > > some interest, simply because the webpage seems to show a dead
> > > project (search about "halo effect")
> > > Not only because of the latest news, but the 90s style appearance
> > > of the website, and the outdated documentation.
> >
> > Who's prejudiced now ? And if we're going that way, then the point I
> > was making in my previous message, which I hoped you would have
> > understood, is that I don't want to work with people who give up
> > because it takes them more than a few seconds to find information, or
> > who evaluate a project based on the look of its web site. You're
> > mentioning the halo effect and you're right, I'd much rather work
> > with people who have as few cognitive biases as possible, so call me
> > prejudiced against the others if you want, at least I have a strong
> > argument for my case.
> >
>
> Please stop arguing, everyone.
> I already made some notes about how to make the web page more readable,
> we'll be judging the effects when its done.
> Don't waste more time on arguing than it's worth.
>
> As for Samuel's and yours opinion about people with cognitive biases,
> etc, remember not everyone who visits the page is a system developer -
> sometimes an unrelated person can visit the page. In this case if that
> person finds the web page interesting (even due to cognitive bias),
> there's a possibility the person will tell others about the finding.
> If the web page looks bad, abandoned, isn't convincing, then the person
> just won't care or even worse, will tell others the Hurd is abandonware.
> There's a small chance an incompetent person will tell their more
> competent friends about it, and that's our chance.
> All I want to do is to increase the probability.
>
>
> Jan Wielkiewicz
>
# GNU Hurd website
## Index
1. Introduction to the Hurd
2. Getting starter (for users)
3. How to contribute (for developers)
4. Documentation
1. How It works: Hurd architecture
2. Developer docs:
1. Source code: list of files and functions
2. Deep details about Hurd and Mach
### Getting started
GNU/Hurd is in active development, and is not stable enough to be used in production environments.
Anyway, you can test GNU/Hurd in virtual machine, and in a some old PCs.
Some GNU/Linux distributions, like Debian, Arch or Guix, have variants based in Hurd.
To start with Hurd, we recomments to use Debian GNU/Hurd.
#### Debian GNU/Hurd
###### Prebuilt images for virtual machines
To give Debian GNU/Hurd a try, it is probably easier to simply run the
preinstalled image, which is provided here:
$ wget http://cdimage.debian.org/cdimage/ports/10.0/hurd-i386/debian-hurd.img.tar.xz
$ tar xJf debian-hurd.img.tar.xz
All the debian-hurd.img* files are the same, they are just in various
format, because it has been reported that some tools are not able to cope with
the sparse tar format. The .tar.xz is still the preferred, as it will produce a
sparse file on your disk. You can compare the resulting .img file with the
MD5SUMS file
It can be run directly in qemu/kvm (make sure that you can access /dev/kvm to
get full KVM speed):
$ kvm -m 1G -drive file=debian-hurd*.img,cache=writeback
It is often convenient to connect through ssh to the box, instead of logging on
the console, this can be done by forwarding the ssh port:
$ kvm -net user,hostfwd=tcp:127.0.0.1:2222-:22 -net nic -drive file=debian-hurd*.img,cache=writeback -m 1G
and then you can connect through ssh:
ssh demo@localhost -p 2222
(don't forget to first set a password for the demo user)
One can increase the size of the image with e.g.:
$ qemu-img resize debian-hurd*.img +5G
$ parted debian-hurd*.img
(parted) resizepart 2 100%
(parted) quit
$ sudo losetup -o $((512*1953792)) /dev/loop0 debian-hurd*.img
$ sudo resize2fs /dev/loop0
$ sudo losetup -d /dev/loop0
(1953792 is the start sector shown in fdisk -l debian-hurd*.img)
It can also be run in virtualbox (though it is much less tested), by first
converting to VDI format :
$ VBoxManage convertfromraw debian-hurd.img debian-hurd.vdi --format vdi
You can then just log in as root without a password.
The qemu/kvm -curses option can be used to run it in text mode, which can help with the
keyboard layout, but it's better to simply reconfigure the layout by running
dpkg-reconfigure keyboard-configuration
You can find more information in https://cdimage.debian.org/cdimage/ports/current-hurd-i386/README.txt
#### Debian GNU/Hurd installation
The preinstalled image allows to do a quick test of the system, but sometimes could be interesting doing our own installation. This section offers a how-to for Debian GNU/Hurd installation.
###### Hardware requirements
+ `>=` 256 MB RAM
+ Wired connection
* NIC compatible with pcnet or Intel e1000
+ Hard Disk:
* SATA AHCI, SATA in IDE-compatible mode or IDE
- CD/DVD drive
##### Download Debian GNU/Hurd images
To install Debian GNU/Hurd, It's necessary to download the iso image.
The latest image can be downloaded from [here](https://cdimage.debian.org/cdimage/ports/latest/hurd-i386/current/)
#### Preparing the environment
- **Real hardware**
Debian GNU/Hurd can works over real hardware, although, depending of the machine, It can suffer many hardware limitation and even, sometimes, don't offers video signal.
Some models which has been tested with successfull results are Thinkpad T60, R60e, X61 and T410.
These models includes good compatibility with network drivers, video and mouse.
For installation over real hardware, It's necessary to burn the iso image over a DVD, and boot the machine using that. Other option could be extract the harddisk, connect It as external, and execute the installer over a virtual machine, setting as destination the external harddisk.
- **Virtual Machine**
If you prefers to install Debian GNU/Hurd over a virtual machine, you can use VirtualBox or Qemu.
For Qemu, you can get a configuration script [here](https://gist.github.com/AlmuHS/73bae6dadf19b0482a34eaab567bfdfa)
For VirtualBox, you can set "Debian (32 bit)" profile, and set the network card model as "pcnet" (add some screenshots of VirtualBox configuration)
#### Installation
Once the installation environment is ready, you can start the installation booting from cdrom (or iso image), and selecting "Pseudographical install" into the installer.
You can read a step-to-step guide to installation [here](https://gist.github.com/AlmuHS/f0c036631881756e817504d28217a910)
(Explain more about installation)
#### After install configurations and some tips
Read https://www.debian.org/ports/hurd/hurd-install
(Add some tips after installing)
### How to contribute
#### Contacting with the developers
To talk with the developer, there are two ways
- Maillist: Hurd has many maillist to write with other users and developers.
Currently, the most active is "bug-hurd". You can join to this maillist from this [link](https://lists.gnu.org/mailman/listinfo/bug-hurd)
- IRC: Hurd has a IRC channel in Freenode, called #hurd
For enter in It, you must to [register a nickname in freenode](https://howchoo.com/g/ndnlnzczmgz/register-nickname-freenode)
Once registered, you can enter to the channel using IRC clients like Pidgin or XChat. Or, from the webbrowser, using [freenode-webchat](https://webchat.freenode.net/)
#### Contributing to source code
##### Getting sources
The Hurd and Mach sources are stored in Savannah (http://git.savannah.gnu.org/cgit/hurd/)
You can download them using Git
For Hurd sources:
git://git.savannah.gnu.org/hurd/hurd.git
For Mach sources
git://git.savannah.gnu.org/hurd/gnumach.git
##### Writing code
- **Preparing environment**
Before start the work, is recommended to create a new git branch. This will makes easier the generation of the patch.
- **Coding style**
To write code, It's recommended to follow the same coding style guide than the rest existent files.
If you're editing a existent file, you might be follow the same style than the rest of the code: check tabulations, spaces between symbols, braces, comments style, etc.
If you're file is new, you can check the rest of the files of the directory. If the directory contains many different coding styles, you can use a standard style:
- Mach coding style, if you're working over GNU Mach
- GNU coding style if you're working over Hurd
(add little documentation for each coding style)
##### Generating the patch
Once finished the work, you can send the contribution sending a patch to the maillist.
The patch will contains the differences between the master branch and your code (usually in other branch), in "diff" format.
You can generate a patch using git, with the command:
git diff master [your_branch] >> [my_mod].patch
replacing [your_branch] with the name of your branch, and [my_mod] with the name of your patch_file
Once generated the patch, you might add a header describing the changes done in the contribution, like a commit, with a format similar to this:
Author: Samuel Thibault <samuel.thiba...@ens-lyon.org>
Date: Sun Jul 19 14:18:16 2020 +0200
device intr: Fix reference leak
On RPC success we have to release the passed send rights, otherwise
references accumulate and we never notice when the receiver dies.
* device/ds_routines.c (ds_device_intr_ack): On success, call
ipc_port_release_send on the notification receive port.
- **Generating a set of patches**
The previous tip can be useful when the list of changes is very short. But, when the patch includes a very big list of changes, the patch can be difficult to review.
To solve this problem, It's possible to split the list of changes in different patches, one for each commit. For this, you can use `git format-patch`, with the syntax:
git format-patch -N
replacing `N` with the number of commits to add in the patch
This command generates a set of patches, with a patch for each commit.
- If the number of commits is long, it's possible to squash them using `git rebase -i` (https://www.internalpointers.com/post/squash-commits-into-one-git)
- But, if the number of commits is even more long (you have "tons of commits"), you can squash them manually, following these steps:
1. Do a `git diff` between your branch and master
2. From the `git diff`, extract each couple of changes to different files
3. Return to master branch, using `git checkout`
4. Generate a new branch, derived from master
5. Apply the patches one to one
1. Apply a patch
2. Check if the changes are applied successfully. Add more changes if necessary
3. Create a new commit with the correct format (using `git commit`, instead `git commit -m`)
4. Once applied all patches and done all commits, execute `git format-patch -N` to generate the patches set
##### Sending the patch
To send the patch to Hurd's developers, you must to send a email to bug-hurd maillist, attaching the set of patches to this. To advice about you're sending a patch, you can add "[PATCH]" prefix to the Subject. Example:
[PATCH]: Fix error in random generator
Wait until developers check your patch. It's possible to ask yours to fix some things.
#### Other contributions
Added to source code, you can contribute with other things: write docs, help with packaging (https://www.debian.org/ports/hurd/hurd-devel-debian)... write to bug-hurd to find more information
https://www.gnu.org/software/hurd/user/tlecarrour/porting_guide_for_dummies.html
