summaryrefslogtreecommitdiff
path: root/web/html/guidelines.html
blob: c2acd772f1563efc002523c8fcba4b9a953d5580 (plain)
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
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head><title>AUR Guidelines</title>
        
			<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
			<link rel="stylesheet" type="text/css" href="http://archlinux.org/docs/css/arch-styles.css"></head>



	<body>
        <h1>AUR Guidelines</h1>
		
        <div class="date">Jun 08, 2005</div>
        <div class="version">1.1.0</div>
		
		<address>
            Ben Mazer
            <a class="email" href="mailto:blm@groknil.org">blm@groknil.org</a>
		</address>
	    <address>
            The Trusted Users
            <a class="email" href="mailto:aur-general@archlinux.org">aur-general@archlinux.org</a>
        </address>

		<h2 id="summary">Summary</h2>
        <p>
            Basic guidelines for the Arch User Repository. 
		</p>

		<h2 id="toc">Table Of Contents</h2>
		<div class="toc">
		<ol>
            <li><a href="#purpose">Purpose</a></li>
            <li><a href="#user">The User</a>
            <ol>
                <li><a href="#usersub">Submitting Packages</a></li>
                
            </ol>
            </li>
            <li><a href="#tu">The TU</a>
            <ol>
                <li><a href="#tuaddition">Adding a TU</a></li>
                <li><a href="#turemoval">Removing a TU</a></li>
                <li><a href="#otherduties">Other Duties</a></li> 
<li><a href="#tuguidelines">Guidelines for Package Maintenance</a>
            <ol>
                <li><a href="#accessing">Accessing the Repo</a></li>
                <li><a href="#adopting">Adopting a package</a></li>
                <li><a href="#disowning">Disowning a package</a></li>
                <li><a href="#pkgguidelines">Packaging Etiquette</a></li>
            </ol>
            </li>  
             

        </ol> </li>
        <li><a href="#faq">Frequently Asked Questions</a></li>
            		</ol>
		</div>

        <h2 id="purpose">Purpose</h2>
        <p>
        The <acronym title="Arch User Repository">AUR</acronym>
is a community of Arch users, where packages outside of the core Arch
distribution are maintained. The AUR Community Repo is a supplement to
the EXTRA and CURRENT repositories; less popular packages will be
maintained as a service to the general Arch-using population. Packages
in the AUR will depend on EXTRA and CURRENT. <br><br> The AUR was
created to lift the burden on the developers. They should be allowed to
focus on adding new features, rather than doing the mundane job of
package maintenance. Therefore, all packages start inside the AUR, and
as developers consider them crucial to the distribution, they will be
adopted into EXTRA/CURRENT. The AUR was also created to allow easy
participation. Arch is completely volunteer-based, and needs help from
its users. Lastly, the AUR helps to further the Arch philosophy of
KISS. The Arch Core (EXTRA/CURRENT/UNSTABLE) is a complete
distribution, but it does not attempt to provide every single package.
The AUR helps by maintaining less popular packages; but the AUR also
follows KISS, and only popular packages from UNSUPPORTED will make it
into the official AUR repository. </p>
        <h2 id="user">The User</h2>
        <p> Users of the
AUR can do many things, the main function being to download and use
packages. One can access the AUR by adding this to their pacman.conf
file:<br><br>
        <code>[community]<br>Server = ftp://ftp.archlinux.org/community/os/i686/</code><br><br>
But a user can also help with package maintenance, by: submitting
packages (and then maintaining them while they remain in UNSUPPORTED),
filing bug reports, reporting out-of-date packages, helping with other
user-submitted PKGBUILDs, and voting for packages that should be
maintained by the TUs. Once a user account has been created, all
functions can be performed inside the web interface. </p><h3 id="usersub">Submitting Packages</h3>
        <p>
Inside the web interface, a user can submit a tarball (tar.gz) of a
directory containing build files for a package. The directory inside
the tarball should contain a PKGBUILD, any .install files, patches, etc
(<b>no binaries</b>). Examples of what a directory looks like can be seen inside /var/abs. <br><br>
        When submitting a package, observe the following rules:
        </p><ul>
            <li>Check
EXTRA, CURRENT, UNSTABLE, UNSUPPORTED, and AUR for the package. If it
is inside any of those repositories in any form, do not submit the
package (if the package is broken in some way, file a bug report). </li>
            <li>Verify
carefully that what you are uploading is correct. Follow the
TU/Developer Package Building Guidelines exactly. Broken packages make
the AUR messy, and prevent the TUs from doing their other duties. </li>
            <li>If
you are unsure about the package (or the build/submission process) in
any way, submit the PKGBUILD to the AUR Mailing List for public review
before adding it to the AUR.</li>
            <li>Make sure the package
is useful. Will anyone else want to use this package? Is it extremely
specialized? If more than a few people would find this package useful,
it is appropriate for submission. </li>
            <li>Gain some experience before submitting packages. Build a few packages to learn the process and then submit. </li>
            <li>Do
not abandon packages. While in UNSUPPORTED, it is the user's job to
maintain the package. If you do not want to maintain the package for
some reason, post a message to the AUR Mailing List. </li>
        </ul>
        
        
        <h2 id="tu">The TU</h2>
        <p>
The TU -or Trusted User- is a member of the community charged with
keeping the AUR in working order. He maintains popular packages, and
votes in administrative matters. A TU is elected from active community
members by current TUs in a democratic process. TUs are the only
members who have a final say in the direction of the AUR. </p>
        <h3 id="tuaddition">Adding a TU</h3>
        <p>
TUs are only added as needed, and applications will only be accepted at
certain times. Check the AUR website for details on whether
applications are being accepted. <br><br>
TUs are elected democratically. If you would like to become a TU, a
sponsor (another TU) is needed. You must solicit requests for a sponsor
privately before posting on the mailing list. After this is received, a
request must be made on the AUR Mailing List by the sponsor. Ideally, a
TU should have a specific subset of packages he wishes to maintain. <br><br>
Four other votes must be received from other TUs or developers for an
applicant to be accepted. Once these have been received, the user will
be given the proper passwords, and a TU will upgrade the user's status
on the web interface. <br><br>
Once an application has been published on the mailing list, it is open
for voting for 3 weeks. If the applicant does not receive enough votes
within that time period, he must wait 3 months to submit another
application, with vote tallies being reset. <br>
        
        </p>
        <h3 id="turemoval">Sanctioning/Removing a TU</h3>
        <p>
There is a basic sanctioning system for TUs. If a TU breaks a rule,
either official or through "community standards" when he was already
aware of this rule, one can request a sanction. If two other votes from
TUs are received, a sanction will be added. After two sanctions, the TU
will automatically come up for a removal vote. <br><br> If a TU is not working out, for any reason, one can
request him to be expelled. Someone requesting a removal of a TU must
state a valid reason, and why immediate removal is necessary. Almost
always, previous sanctions will be needed. With four additional votes,
that TU will be immediately removed and his packages will have to be
adopted by a different TU. </p>
        <h3 id="otherduties">Other Duties</h3>
        <p>
All other duties (changing rules, adding new regulations, new features,
etc) should be discussed openly on the AUR Mailing List and voted on.
Various pieces of documentation and code can have specified
"maintainers" that can perform basic updates (typo/bug fixes) without a
vote, but any changes should be reported on the mailing list. Any major
changes should receive a simple majority vote. </p>
        <h3 id="tuguidelines">Guidelines for Package Maintenance</h3>
        <p>
        </p>
        <h4 id="accessing">Accessing the Repo</h4>
        <p>
        Follow these instructions for uploading/modifying packages once you have become a TU:
        </p><ol>
            <li>Install the "aurtools" package.</li>
            <li>Email Jason (<a class="email" href="mailto:jason@archlinux.org">jason@archlinux.org</a>) for a CVS account.</li>
            <li>Run the following commands to checkout the AUR CVS:<br>
            <kbd>
                export CVSROOT=":pserver:&lt;userid&gt;@cvs.archlinux.org:/home/cvs-community"<br>
                cvs login<br>
                cvs co community</kbd></li>
            <li>To add a PKGBUILD and other build files:<br>
            <kbd>
                cvs add &lt;directory&gt;<br>
                cd &lt;directory&gt;<br>
                cvs add PKGBUILD<br>
                .<br>
                .<br>
                cvs commit</kbd></li>
            <li>To upload a binary package:
            <kbd>tupkg --user &lt;userid&gt; --password &lt;password&gt; &lt;packagefile.pkg.tar.gz&gt;</kbd></li>
            <li>After uploading a package and committing the build files, tag the files with this command:
            <kbd>cvs tag -cFR CURRENT &lt;newpackagebuilddir&gt;</kbd></li>
            <li>Package
changes should be available within 10 minutes. Verify everything was
uploaded properly, then select the newly added or updated package in
the web interface and set yourself as the maintainer.</li>
        </ol>
        
        <h4 id="adopting">Adopting Packages</h4>
        <p>
A TU may adopt any package at any time. But because the TU's time is
limited, he should try to only adopt popular packages. The voting
mechanism in the AUR allows a TU to quickly gage which packages users
want. <br><br>
If a package receives 25 votes, it may be adopted by a TU. A maintainer
should adopt it via the web interface. That maintainer is then
responsible for bug fixes and new version updates. Packages must be
properly cleaned and fixed after adoption. </p>

        <h4 id="disowning">Disowning packages</h4>
        <p>
If a TU can't or doesn't want to maintain a package any longer, a
notice should be posted to the AUR Mailing List, so another TU can
maintain it. A package can still be disowned even if no other TU wants
to maintain it, but the TUs should try not to drop many packages (they
shouldn't take on more than they have time for). If a package has
become obsolete or isn't used any longer, it can be removed completely
as well. <br><br>
If a package has been removed completely, it can be uploaded once again
(fresh) to UNSUPPORTED, where a regular user can maintain the package
instead of the TU. </p>
        <h4 id="pkgguidelines">Packaging Etiquette</h4>
        <p>
        Adhere to the following rules when building/maintaining packages:
        <br>
        </p><ul>
            <li>Follow all rules in the <a href="http://www.archlinux.org/docs/en/guide/install/arch-install-guide.html#build">Arch Packaging Guidelines</a>.</li>    
            <li>Always run Namcap on all packages and PKGBUILDs.</li>
            <li>All
important messages should be echoed inside the .install file. For
example, if a package needs extra setup to work, directions should be
echoed. </li>
            <li>Any optional dependencies that aren't
needed to run the package or have it generally function shouldn't be
included, but a warning message inside the .install file should echo
something like: "To enable SMB support, download the Samba package."</li>
            
            <li>Always look at current packages for ideas on how various problems should be handled. Most problems have already been solved. </li>
            <li>Dependencies
are the most common packaging error. Namcap can help detect them, but
it is not always correct. Verify dependencies by looking at source
documentation and the program website. </li>
            <li>All packages should be buildable as a user, under fakeroot. </li>
            <li>New user creation should only be done when absolutely necessary. </li>
            <li>Always
fill out all applicable fields in the PKGBUILD (never forget a URL,
md5sum, etc). The LICENSE variable is not currently used, but will be
very shortly. </li>
            <li>All custom variables should begin with an underscore (_). </li>
            <li>A PKGBUILD should never modify any files outside of the build directory. </li>
        </ul>
        
        <h2 id="faq">Frequently Asked Questions</h2>
        <p>
        Q: What is the difference between the AUR, COMMUNITY, and TUR? Why don't packages I upload to the AUR show up in pacman?<br><br>
A: The TUR, or Trusted User Repository, was the old system used to
manage user submissions. It had a number of flaws, so was discontinued.
The TUR website is still up, but is dead and will be removed shortly.
AUR is the official replacement for the TUR. It is a web system that
allows users to submit their own PKGBUILDs for both the TUs and the
general community to see. COMMUNITY is a new Arch repository, run by
the TUs, that is available via pacman.<br><br>
User submitted PKGBUILDs are available from the AUR, but because they
have not been reviewed, packages are not available. If a PKGBUILD is
reviewed, and receives many votes, it may "graduate" into the COMMUNITY
repo. There it will easily be retrievable from pacman.<br><br>
If you are a new user, it is safe to use the COMMUNITY repo, as
packages have been verified. Any PKGBUILDs in the UNSUPPORTED section
of the AUR have not been tested, and could be dangerous or broken. Use
at your own risk. </p>
    </body></html>