/[gentoo]/xml/htdocs/proj/en/glep/glep-0043.txt
Gentoo

Contents of /xml/htdocs/proj/en/glep/glep-0043.txt

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (hide annotations) (download)
Mon Nov 7 21:55:08 2005 UTC (8 years, 11 months ago) by ciaranm
Branch: MAIN
File MIME type: text/plain
Add glep 43

1 ciaranm 1.1 GLEP: 43
2     Title: GLEP File Hosting
3     Version: $Revision: $
4     Author: Ciaran McCreesh <ciaranm@gentoo.org>
5     Last-Modified: $Date: $
6     Status: Draft
7     Type: Informational
8     Content-Type: text/x-rst
9     Created: 7-Nov-2005
10     Post-History: 7-Nov-2005
11    
12     Abstract
13     ========
14    
15     This GLEP proposes the creation of a reliable hosting location for data (e.g.
16     sample code) associated with GLEPs.
17    
18     Motivation
19     ==========
20    
21     Some GLEPs come with non-trivial example files or code which are part of the
22     specification. There are two methods which have been used to handle this
23     previously:
24    
25     * Include the code inline in the GLEP using a code (``::``) segment. This is
26     less than ideal for larger code samples as it leads to considerable clutter.
27     * Place the files on a developer's webspace on ``dev.gentoo.org``. This is not
28     particularly reliable -- developers may leave or accidentally restructure
29     their webspace, and a GLEP is intended to be a *permanent* specification.
30    
31     This GLEP proposes that GLEP authors be allowed to make use of the main Gentoo
32     webserver for hosting content relevant to their GLEP.
33    
34     .. Important:: The hosting proposed is for files related to the **proposal**
35     (e.g. example code which clarifies part of the specification), not a full
36     implementation of the proposal.
37    
38     Specification
39     =============
40    
41     Once a GLEP number has been allocated, developers (or the GLEP editors) may
42     create a directory in CVS named ``glep-xxxx-extras/`` (where ``xxxx`` is the
43     GLEP's number) under the main GLEP directory. This directory may be used by
44     files which are part of the proposal.
45    
46     Any hyperlinks to files inside this directory should use relative paths. This
47     prevents breakages in the case of directory structure changes.
48    
49     GLEPs which use this directory may include an 'Example Files' heading with a
50     list of links to the associated files.
51    
52     Example
53     -------
54    
55     Consider the following GLEP segment, which has been taken from a draft of
56     GLEP 42 [#glep-42]_:
57    
58     ::
59    
60     Example News Item
61     '''''''''''''''''
62    
63     The following hypothetical news item could be used for an upgrade to the
64     ``YourSQL`` database format which breaks forward compatibility. It should be
65     named ``2005-11/2005-11-01-yoursql-upgrades.en.txt``.
66    
67     ::
68    
69     # Lots and lots of lines of example news item
70    
71     The news item in question is clearly part of the proposal, but including it
72     inline is messy. Under this proposal, the main GLEP segment would read:
73    
74     ::
75    
76     Example News Item
77     '''''''''''''''''
78    
79     `This hypothetical news item`__ could be used for an upgrade to the
80     ``YourSQL`` database format which breaks forward compatibility. It would be
81     named ``2005-11/2005-11-01-yoursql-upgrades.en.txt``.
82    
83     .. __: glep-0042-extras/example-news-item.txt
84    
85     The example news item would then be placed in
86     ``glep-0042-extras/example-news-item.txt``\.
87    
88     Similar changes would be made for the longer example code segments. The GLEP
89     could also gain a new section along the lines of:
90    
91     ::
92    
93     Example Files
94     =============
95    
96     `example-news-item.txt <glep-0042-extras/example-news-item.txt>`_
97     An example news item.
98     `news-mailer.bash <glep-0042-extras/news-mailer.bash>`_
99     A ``bash`` script which delivers news items via email.
100    
101     Backwards Compatibility
102     =======================
103    
104     Not an issue.
105    
106     References
107     ==========
108    
109     .. [#glep-42] GLEP 42: Critical news reporting, Ciaran McCreesh,
110     http://www.gentoo.org/proj/en/glep/glep-0042.html
111    
112     Copyright
113     =========
114    
115     This document has been placed in the public domain.
116    
117     .. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et :

  ViewVC Help
Powered by ViewVC 1.1.20