diff options
Diffstat (limited to 'contributing')
| -rw-r--r-- | contributing/web_pages.mdwn | 122 |
1 files changed, 72 insertions, 50 deletions
diff --git a/contributing/web_pages.mdwn b/contributing/web_pages.mdwn index 9a9cc54c..d2ab93f6 100644 --- a/contributing/web_pages.mdwn +++ b/contributing/web_pages.mdwn @@ -9,6 +9,13 @@ 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: @@ -17,22 +24,32 @@ projects: * 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. +## Staging Area + When you commit changes, either using the web interface or checking them in into the repository, they'll not become visible on <http://www.gnu.org/software/hurd/> immediatelly, but first of all only on @@ -52,33 +69,35 @@ you to a page where you have to create an account. After logging in, you can edit the pages. -# Working on a Checkout of the git Repository +# 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. +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* 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 +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. +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 + $ 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 +`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 + $ git config --global user.name 'Your Name' + $ git config --global user.email you@somewhere.invalid +## Getting the Sources For being able to do a checkout from which you can later directly push your changes back into the master repository, you need a @@ -86,7 +105,7 @@ changes back into the master repository, you need a the *hurd-web* 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:~hurd-web/hurd-web [dest] + $ 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 the pages the read-only way. @@ -94,70 +113,73 @@ still get the pages the read-only way. Note that this -- currently -- is not the data from the master server, but from a mirror of it, so it may be lacking behind a bit from time to time. - $ git clone git://git.savannah.gnu.org/hurd/web.git [dest] + $ git clone git://git.savannah.gnu.org/hurd/web.git [dest] -If that also doesn't work out, you have yet another chance: pull over the http +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] + $ 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. (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.) +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, even better would be to do a `git fetch`, followed by a `git +rebase origin/master` 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 - [...] - $ [...] + $ 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. + $ 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. +## 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... + $ 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 - [...] + $ 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. @@ -165,8 +187,8 @@ 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 - [...] + $ 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 |