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

Last change on this file since 4478 was 4478, checked in by fkr, 17 years ago

Bug:
Submitted by:
Reviewed by:
Approved by:
Obtained from:

big guide-update from wbb@. Thanks Will!

  • Property svn:eol-style set to native
File size: 8.2 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 or INLINE
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
211================INLINE CONTENT================
212--
213your sig if you'd like
214]]> 
215                                                </programlisting>
216                                                               
217                                                </listitem>
218                                        </varlistentry>
219                                </variablelist>
220                               
221                        </sect3>
222                       
223                        <sect3>
224                                <title>Final comments on Port submission</title>
225                       
226                                <para>The following general points should also be borne in
227                                mind when submitting to bugzilla:
228                                        <simplelist type="vert">
229                                                <member>Small changes or portfiles should be
230                                                inlined. </member>
231                                                <member>Larger changes should be attached as a
232                                                single file, tar works wonderfully for this. </member>
233                                               
234                                                <member>Multiple patched files should be bundled
235                                                together using tar and attached to the submission</member>
236                                               
237                                                <member>Currently attachments must be sent in
238                                                using the current bug number, remeber to query
239                                                bugzilla to find out the current bug number, select
240                                                 that bug and use the 'Create a New Attachment'
241                                                 link.</member>
242                                                 
243                                        </simplelist></para>
244
245                        </sect3>
246                </sect2>
247                <sect2>
248                        <title>Updating a port</title>
249                        <para>The following guidelines are for submitting updates to
250                        ports that are currently in the tree</para>
251
252                        <para>All updates and modifications to existing ports should
253                        be sent in as diffs.</para>
254                        <para>There are a couple of ways to obtain correct diff
255                        formats</para>
256                        <para>Using diff:
257                                <simplelist type="vert">
258                                        <member>Obtain the original file (oldfile)</member>
259                                       
260                                        <member>cp oldfile oldfile.new</member>
261                                       
262                                        <member>edit oldfile.new and save your changes</member>
263                                       
264                                        <member>diff -u oldfile oldfile.new > oldfile.diff</member>
265                                       
266                                        <member>Use bugzilla to submit your port UDPATE</member>
267                                       
268                                </simplelist></para>
269
270                        <para>Or using cvs diff:
271                                <simplelist type="vert">
272                                        <member>checkout the original source using cvs</member>
273                                        <member>edit the files and save your changes</member>
274                                        <member>cvs diff -u sourcefile > sourcefile.diff</member>
275                                        <member>use bugzilla to submit your port UPDATE</member>
276                                </simplelist></para>
277
278                        <para>Lastly, if your update consists of several files, use tar
279                        to bundle them into one file for submission</para>
280
281                </sect2>
282        </sect1>
283</chapter>
Note: See TracBrowser for help on using the repository browser.