diff options
Diffstat (limited to 'glep-0043.rst')
-rw-r--r-- | glep-0043.rst | 125 |
1 files changed, 125 insertions, 0 deletions
diff --git a/glep-0043.rst b/glep-0043.rst new file mode 100644 index 0000000..2bb5ec5 --- /dev/null +++ b/glep-0043.rst @@ -0,0 +1,125 @@ +GLEP: 43 +Title: GLEP File Hosting +Version: $Revision$ +Author: Ciaran McCreesh <ciaranm@gentoo.org> +Last-Modified: $Date$ +Status: Final +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 work is licensed under the Creative Commons Attribution-ShareAlike 3.0 +Unported License. To view a copy of this license, visit +http://creativecommons.org/licenses/by-sa/3.0/. + +.. vim: set tw=80 fileencoding=utf-8 spell spelllang=en et : |