[darcs-users] RFC: Third-party applications directory

[Alberto Bertogli]

On Sat, Dec 31, 2005 at 11:37:48AM +0000, Pedro Melo wrote:
> My suggestion:
> 
>  - _darcs/third_party is the base for all this;
>  - BASE/common can have common attributes to all applications. We  
> could have a wiki page as the "official" spec. Some of the attributes  
> would include:
>    - description: one line short description of the repo, plain-text;
>    - abstract: longer description of the project. The first line can  
> be a "Content-type: MIME\n\n". If not present assume text/plain;
>    - project_homepage: an URL
>    - authors (?): list of authors? Different from owner/author of  
> the repo sometimes.
>  - BASE/app_name: you own private variables.

Well, since I guess we all agree on the basics, here's a small draft for a
proposal we can build on (or discard, if you think it's crap). Please let
me know what you think of it =)

I've included what's shown up there, except for the authors part, which I
don't find really clear (is it a list of people who commited? arbitrary
list of authors? is that really useful and meaningful?) and I prefer to
add it later if necessary.

I've also added an "encoding" file, because I think that's really useful
for most, if not all, third-party applications in some way.

Thanks,
		Alberto



Third-party applications directory
----------------------------------

Introduction
------------

This document specifies the policy third-party applications should follow
if they want to be nice to the rest of the darcs community and make the
world a better place for the children.

It was written taking David Roundy's suggestion as a base, you can find it
in
http://www.abridgegame.org/pipermail/darcs-users/2005-November/008745.html.

If you don't agree with this document, please don't ignore it, but discuss
the issues with the community so we can all benefit from comments and
present the user a coherent interface he can rely on.

You can send comments to the darcs-users and/or darcs-devel mailing lists.
Please do NOT modify this Wiki page without authorization, as it is used
as a standard guide. Suggestions should be sent to the list to be
discussed, and modifications will be done appropiately when there's
agreement.


Directory layout
----------------

Third party applications that need to store repository-specific data can
make use of the "_darcs/third_party/" directory.

They should create a directory named after their application, like
"_darcs/third_party/darcs2rss/" and place appropiate files there.

What's stored inside this application-specific directory is up to the
application author.

As a recommendation, remember that darcs runs in multiple platforms,
including Windows, where filenames are case-insensitive. If you expect
your application to be portable, don't rely on file casing.


The "common" directory
----------------------

There's a special directory, "_darcs/third_party/common/", where a defined
set of files that most third-party applications find useful are stored.

You should NOT store additional files there, or modify them automatically.

You should only modify them under user authorization, and after notifying
that those settings are shared with other applications.

The following is the list of files that live in this directory, along with
their description. Examples are below.

* description
	A one-line, plain description of the repository, in the repository
	encoding.
* project_homepage
	The URL of the project the repository refers to. Only one, in one
	line, properly escaped if necesary.
* abstract
	A brief description of the project. It can span multiple lines.
	It should be in plain text in the repository encoding, unless you
	specify, in the first line, the content type in MIME-style.
* encoding
	The encoding used for repository data and metadata (ie. covers
	files AND patch descriptions).


Samples
-------

* description

"David Advanced RCS"
"An awesome client for the Jabber network"
"Peter's Linux kernel tree"


* project_homepage

"http://project.example.com/"
"http://ran.out.of.ideas.com/project"


* abstract

"""\
This is a frobobulus oxygenation module for Apache 2.0.

It oxygenates the incoming requests and frobobules your pages before
serving them, gaining up to 12% in performance.
"""

"""\
Content-type: text/html; charset=utf-8

<html>
<head><title>HTML fan</title></head>
<body>
<h1>HTML fan project</h1>

This is an HTML fan project. It ventilates your HTML and makes it
cooler.<br>
</body>
</html>
"""


* encoding

"utf8"
"iso-8859-1"
"ascii"
"cp850"