1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
[[license text="""
Copyright © 2007 Free Software Foundation, Inc.
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.txt]].
"""]]
# How to Contribute to This Wiki
(!) 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.
Before doing any changes, you are encouraged to play a bit in this wiki's
[[SandBox]], to become familiar with the [[MarkDown]] syntax.
## 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*|public_hurd_boxen]] 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.
$ git clone git://flubber.bddebian.com/git/wiki [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/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.
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 mach/issues.mdwn
$ git add mach/issues.mdwn
$ git commit 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 HowToContributeToThisWiki.mdwn
rendering HowToContributeToThisWiki.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.
|
