source: trunk/doc/guide/xml/project/submission.xml @ 10598

Last change on this file since 10598 was 10598, checked in by toby, 15 years ago

Clarify this a bit; it's ok to attach small patches.

  • Property svn:eol-style set to native
File size: 8.1 KB
Line 
1<?xml version="1.0" encoding="UTF-8" ?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="submission">
5        <chapterinfo>
6                <keywordset>
7                        <keyword>
8                                portfile
9                        </keyword>
10                        <keyword>
11                                submissions
12                        </keyword>
13                        <keyword>
14                                maintainer
15                        </keyword>
16                </keywordset>
17        </chapterinfo>
18        <title>DarwinPorts submissions</title> 
19        <sect1>
20                <title>Submitting a Port</title> 
21               
22                <para>Using a standardised approach to submitting the Portfiles and
23                associated patches scripts, etc allows us to keep track of port
24                submissions, process them efficiently and get them submitted as
25                quickly as possible to our dports CVS tree. The following sections
26                will describe the standard port submission procedures. </para>
27               
28                <sect2>
29                        <title>Where to submit</title>
30                       
31                        <para> All ports should be submitted via the DarwinPorts
32                        <ulink url="http://www.opendarwin.org/bugzilla/">bugzilla tool
33                        </ulink>. Your submission will be automatically emailled to the
34                        members of the
35                        <ulink url="http://www.opendarwin.org/mailman/listinfo/darwinports-bugs/">
36                        darwinports-bugs</ulink> mailing list. If you are uncertain about
37                        any aspect of your port, you may also want to email it with your
38                        questions and the bug number to 
39                        <ulink url="mailto:darwinports@opendarwin.org">DarwinPorts</ulink> 
40                        mailing list.</para>
41                       
42                        <para>If you are submitting a modification, or an update to an
43                        existing port, please assign the port to the current maintainer
44                        in your bugzilla submission, so that the automatic email is
45                        directed to the maintainer, who will be best suited to deal
46                        with your submission.</para>
47                       
48                        <para>Updates and modifications should be submitted as diffs. See
49                        updating a port below</para>
50                       
51                </sect2>
52               
53                <sect2>
54               
55                        <title>Using bugzilla to submit a Port</title>
56                       
57                        <para>The following section describes in some more detail how to
58                        use Bugzilla to submit your port.</para>
59                       
60                        <sect3>
61                                <title>Submission parameters</title>
62                               
63                                <variablelist>
64                                        <varlistentry id='Project'>
65                                                <term>
66                                                        Project:
67                                                </term>
68                                                <listitem>
69                                                        <para>Make sure you select the DarwinPorts
70                                                        project.</para>
71
72                                                </listitem>
73                                        </varlistentry>
74                                       
75                                        <varlistentry id='Component'>
76                                                <term>
77                                                        Component:
78                                                </term>
79                                                <listitem>
80                                                        <para>Select "dports" as the component. </para>
81
82                                                </listitem>
83                                        </varlistentry>
84                                       
85                                        <varlistentry id='Assigned_to'>
86                                                <term>
87                                                        Assigned to:
88                                                </term>
89                                                <listitem>
90                                                        <para>Please assign UPDATEs and COMMENTs on
91                                                        existing ports to the maintainer. Otherwise, if
92                                                        this is a NEW port or an RFC, please leave
93                                                        blank. </para>
94
95                                                </listitem>
96                                        </varlistentry>
97                                        <varlistentry id='URL'>
98                                                <term>
99                                                        URL:
100                                                </term>
101                                                <listitem>
102                                                        <para>You may use this field to point to the
103                                                        portfile if it is available online, or to point
104                                                        to the homepage of the program project.</para>
105
106                                                </listitem>
107                                        </varlistentry>
108                                        <varlistentry id='Summary'>
109                                                <term>
110                                                        Summary:
111                                                </term>
112                                                <listitem>
113                                                        <para>The summary field should one of a number
114                                                        of standardised elements, </para>
115
116                                                                <variablelist>
117                                                                        <varlistentry id='NEW_portname'>
118                                                                                <term>NEW: portname-1.2.3
119                                                                                </term>
120                                                                                <listitem>
121                                                                                        <para>Please use this format for
122                                                                                        the submission of new ports.</para>
123
124                                                                                </listitem>     
125                                                                        </varlistentry>
126                                                                        <varlistentry id='UPDATE_portname'>
127                                                                                <term>UPDATE portname-1.2.3
128                                                                                </term>
129                                                                                <listitem>
130                                                                                        <para>Please use this format for
131                                                                                        the submission of updates to ports.
132                                                                                        Please use diffs!</para>
133
134                                                                                </listitem>     
135                                                                        </varlistentry>
136                                                                        <varlistentry id='REVISION_portname'>
137                                                                                <term>REVISION: portname-1.2.3
138                                                                                </term>
139                                                                                <listitem>
140                                                                                        <para>Please use this format for the
141                                                                                        submission of changes to a current,
142                                                                                        uncommitted port submission</para>
143
144                                                                                </listitem>     
145                                                                        </varlistentry>
146                                                                        <varlistentry id='RFC_portname'>
147                                                                                <term>RFC: portname-1.2.3
148                                                                                </term>
149                                                                                <listitem>
150                                                                                        <para>Please use this format for
151                                                                                        the submission of Request for
152                                                                                        Comments on a Portfile.</para>
153
154                                                                                </listitem>     
155                                                                        </varlistentry>
156                                                                        <varlistentry id='ATTACHMENT_portname'>
157                                                                                <term>ATTACHMENT: portname-1.2.3
158                                                                                </term>
159                                                                                <listitem>
160                                                                                        <para>to add an attachment you
161                                                                                        will have use the query tool.
162                                                                                        Once you have selected the correct
163                                                                                        port, please use this format in the
164                                                                                        summary field for your
165                                                                                        submission. </para>
166
167                                                                                </listitem>     
168                                                                        </varlistentry>
169                                                                        <varlistentry id='COMMENT_portname'>
170                                                                                <term>COMMENT: portname-1.2.3
171                                                                                </term>
172                                                                                <listitem>
173                                                                                        <para>Please use this format for
174                                                                                        the submission of comments on
175                                                                                        existing ports or submissions.
176                                                                                        Most comments should be directed
177                                                                                        to the maintainer, or the mailing
178                                                                                        lists. Some comments are of a
179                                                                                        critical nature and should be
180                                                                                        logged.</para>
181
182                                                                                </listitem>     
183                                                                        </varlistentry>
184                                                                </variablelist>
185                                                               
186                                                </listitem>
187                                        </varlistentry>
188                                        <varlistentry id='Description'>
189                                                <term>
190                                                        Description:
191                                                </term>
192                                                <listitem>
193                                                        <para>The description field should contain the
194                                                        following information as per the example given
195                                                        here here. </para>
196
197                                                                <programlisting>
198<![CDATA[
199Portname-1.2.3
200
201the portfile can be found here: URL or ATTACHED
202
203Description: What does this program do in a nutshell,
204briefly what changes were made, or what files you are attaching in the tarball.
205
206Homepage: URL of project or program itself, not the portfile
207
208Comments: Any comments you have about your port, concerns, lookouts,
209dependencies that you may want to mention
210--
211your sig if you'd like
212]]> 
213                                                </programlisting>
214                                                               
215                                                </listitem>
216                                        </varlistentry>
217                                </variablelist>
218                               
219                        </sect3>
220                       
221                        <sect3>
222                                <title>Final comments on Port submission</title>
223                       
224                                <para>The following general points should also be borne in
225                                mind when submitting to bugzilla:
226                                        <simplelist type="vert">
227                                                <member>Small changes may be attached or included
228                                                in the description field.</member>
229                                                <member>Larger changes should be attached as a
230                                                single file.</member>
231                                                <member>Multiple patched files should be bundled
232                                                together using tar and attached to the submission.</member>
233                                                <member>Currently attachments must be sent in
234                                                using the current bug number, remeber to query
235                                                bugzilla to find out the current bug number, select
236                                                 that bug and use the 'Create a New Attachment'
237                                                 link.</member>
238                                        </simplelist></para>
239
240                        </sect3>
241                </sect2>
242                <sect2>
243                        <title>Updating a port</title>
244                        <para>The following guidelines are for submitting updates to
245                        ports that are currently in the tree</para>
246
247                        <para>All updates and modifications to existing ports should
248                        be sent in as diffs.</para>
249                        <para>There are a couple of ways to obtain correct diff
250                        formats</para>
251                        <para>Using diff:
252                                <simplelist type="vert">
253                                        <member>Obtain the original file (oldfile)</member>
254                                       
255                                        <member>cp oldfile oldfile.new</member>
256                                       
257                                        <member>edit oldfile.new and save your changes</member>
258                                       
259                                        <member>diff -u oldfile oldfile.new > oldfile.diff</member>
260                                       
261                                        <member>Use bugzilla to submit your port UDPATE</member>
262                                       
263                                </simplelist></para>
264
265                        <para>Or using cvs diff:
266                                <simplelist type="vert">
267                                        <member>checkout the original source using cvs</member>
268                                        <member>edit the files and save your changes</member>
269                                        <member>cvs diff -u sourcefile > sourcefile.diff</member>
270                                        <member>use bugzilla to submit your port UPDATE</member>
271                                </simplelist></para>
272
273                        <para>Lastly, if your update consists of several files, use tar
274                        to bundle them into one file for submission</para>
275
276                </sect2>
277        </sect1>
278</chapter>
Note: See TracBrowser for help on using the repository browser.