-- Leo's gemini proxy

-- Connecting to git.thebackupbox.net:1965...

-- Connected

-- Sending request

-- Meta line: 20 text/gemini

repo: gemini-site
action: commit
revision:
path_from:
revision_from: a69088ed634f0e3e5684194e6de35e84952c83aa:
path_to:
revision_to:

commit a69088ed634f0e3e5684194e6de35e84952c83aa
Author: Solderpunk <solderpunk@sdf.org>
Date:   Wed Oct 23 16:20:24 2019 +0000

    Initial version of Best Practices document.

diff --git a/best-practices.txt b/best-practices.txt
new file mode 100644
index 0000000000000000000000000000000000000000..500a0b3177530cf8bbce6463b01db98f2675a1b1
--- /dev/null
+++ b/best-practices.txt
@@ -0,0 +1,85 @@
+# Best practices for Gemini implementations
+
+## Introduction
+
+This document describes various conventions
+and snippets of advice for implementing and
+using the Gemini protocol which, while not
+mandated by the protocol specification, are
+generally considered a good idea.  If you're
+writing Gemini software or building a Gemini
+site, you should generally follow the advice
+given here unless you have good reasons not
+to.
+
+## Filenames
+
+Gemini servers need to inform clients of the
+MIME type of the files they are serving.  The
+most convenient way for servers to figure out
+the MIME type of files is via the extension
+of the filename.  These mappings are mostly
+well-standardised (and unix systems often
+have an /etc/mime.types file full of them),
+but the question remains as to how servers
+should recognise files to be served with the
+text/gemini type defined by Gemini.
+
+Current Gemini servers seem to use .gmi or
+.gemini extensions for this purpose, and new
+servers are strongly encouraged to support
+one or both of these options instead of
+adding a new one to the mix.
+
+Following the convention for webservers, if a
+request is received for a path which maps to
+a directory in the server's filesystem and a
+file named index.gmi or index.gemini exists
+in that directory, it is served up for that
+path.
+
+## File size
+
+Gemini servers do not inform clients of the
+size of files they are serving, which can
+make it difficult to detect if a connection
+is closed prematurely due to a server fault.
+This risk of this happening increases with
+file size.
+
+Gemini also has no support for compression of
+large files, or support for checksums to
+enable detection of file corruption, the risk
+of which also increases with file size.
+
+For all of these reasons, Gemini is not well
+suited to the transfer of "very large" files.
+Exactly what counts as "very large" depends
+to some extent on the speed and reliability
+of the internet connections involved, and the
+patience of the users.  As a rule of thumb,
+files larger than 100MiB might be thought of
+as best served some other way.
+
+Of course, because Gemini supports linking to
+other online content via any protocol with a
+URL scheme, it's still possible to link from
+a Gemini document to a large file served via
+HTTPS, BitTorrent, IPFS or whatever else
+tickles your fancy.
+
+## Text encoding
+
+Gemini supports any text encoding you like
+via the "charset" parameter of text/* MIME
+types.  This allows serving "legacy" text
+content in obscure regional encoding schemes.
+
+For new content, please, please, please just
+use UTF-8.  The Gemini specification mandates
+that clients be able to handle UTF-8 text.
+Support for any other encoding is up to the
+client and is not guaranteed.  Serving your
+content as UTF-8 maximises its accessibility
+and maximises the utility of simple clients
+which support only UTF-8.

-- Response ended

-- Page fetched on Sun Jun 2 16:18:15 2024