diff options
Diffstat (limited to 'contributing')
| -rw-r--r-- | contributing/questionnaire.mdwn | 45 | ||||
| -rw-r--r-- | contributing/web_pages.mdwn | 230 | ||||
| -rw-r--r-- | contributing/web_pages/news.mdwn | 110 | ||||
| -rw-r--r-- | contributing/web_pages/news/merge-news | 13 | ||||
| -rw-r--r-- | contributing/web_pages/news/skeleton.mdwn | 62 |
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>) + +"""]] |