en/glep/glep-0043.txt

GLEP: 43
Title: GLEP File Hosting
Version: $Revision: 1.1 $
Author: Ciaran McCreesh <ciaranm@gentoo.org>
Last-Modified: $Date: 2005/11/07 21:55:08 $
Status: Draft
Type: Informational
Content-Type: text/x-rst
Created: 7-Nov-2005
Post-History: 7-Nov-2005

Abstract
========

This GLEP proposes the creation of a reliable hosting location for data (e.g.
sample code) associated with GLEPs.

Status
======

This GLEP has been approved by the GLEP editor and marked Final on
13 Nov. 2005.

Motivation
==========

Some GLEPs come with non-trivial example files or code which are part of the
specification. There are two methods which have been used to handle this
previously:

* Include the code inline in the GLEP using a code (``::``) segment. This is
  less than ideal for larger code samples as it leads to considerable clutter.
* Place the files on a developer's webspace on ``dev.gentoo.org``. This is not
  particularly reliable -- developers may leave or accidentally restructure
  their webspace, and a GLEP is intended to be a *permanent* specification.

This GLEP proposes that GLEP authors be allowed to make use of the main Gentoo
webserver for hosting content relevant to their GLEP.

.. Important:: The hosting proposed is for files related to the **proposal**
   (e.g. example code which clarifies part of the specification), not a full
   implementation of the proposal.

Specification
=============

Once a GLEP number has been allocated, developers (or the GLEP editors) may
create a directory in CVS named ``glep-xxxx-extras/`` (where ``xxxx`` is the
GLEP's number) under the main GLEP directory. This directory may be used by
files which are part of the proposal.

Any hyperlinks to files inside this directory should use relative paths. This
prevents breakages in the case of directory structure changes.

GLEPs which use this directory may include an 'Example Files' heading with a
list of links to the associated files.

Example
-------

Consider the following GLEP segment, which has been taken from a draft of
GLEP 42 [#glep-42]_:

::

    Example News Item
    '''''''''''''''''

    The following hypothetical news item could be used for an upgrade to the
    ``YourSQL`` database format which breaks forward compatibility. It should be
    named ``2005-11/2005-11-01-yoursql-upgrades.en.txt``.

    ::

        # Lots and lots of lines of example news item

The news item in question is clearly part of the proposal, but including it
inline is messy. Under this proposal, the main GLEP segment would read:

::

    Example News Item
    '''''''''''''''''

    `This hypothetical news item`__ could be used for an upgrade to the
    ``YourSQL`` database format which breaks forward compatibility. It would be
    named ``2005-11/2005-11-01-yoursql-upgrades.en.txt``.

    .. __: glep-0042-extras/example-news-item.txt

The example news item would then be placed in
``glep-0042-extras/example-news-item.txt``\.

Similar changes would be made for the longer example code segments. The GLEP
could also gain a new section along the lines of:

::

    Example Files
    =============

    `example-news-item.txt <glep-0042-extras/example-news-item.txt>`_
        An example news item.
    `news-mailer.bash <glep-0042-extras/news-mailer.bash>`_
        A ``bash`` script which delivers news items via email.

Backwards Compatibility
=======================

Not an issue.

References
==========

.. [#glep-42] GLEP 42: Critical news reporting, Ciaran McCreesh,
   http://www.gentoo.org/proj/en/glep/glep-0042.html

Copyright
=========

This document has been placed in the public domain.

.. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et :

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