Lady’s Gitweb - x_status_git/blob - README.markdown

   1 # Status.git
   2
   3 A minimal git‐based self‐hosted status publishing solution.
   4
   5 ## What It Is
   6
   7  +  A Python script, `post-receive`, suitable for use as a post‐receive
   8       Git hook, which generates a number of `.jsonld` files from a
   9       source repository of text posts.
  10
  11  +  A small collection of H·T·M·L files designed to display the
  12       generated `.jsonld` in a human‐readable fashion.
  13
  14 ## What It Is Not
  15
  16  +  A server or server configuration (you will need to supply these
  17       yourself; see below).
  18
  19  +  Suitable for deployment on a simple filesystem server like
  20       NeoCities or GitHub Pages (it requires both Git hooks and H·T·T·P
  21       routing).
  22
  23  +  Interactive in any way (i·e “social media”).
  24
  25  +  Compatible with the ActivityPub fediverse (or any other push‐based
  26       social media platform).
  27
  28 ## Script Configuration
  29
  30 You will need to edit the `post-receive` script to adjust the following
  31   constants to match your setup :—
  32
  33  +  **`GIT_DIRECTORY`**:
  34     The absolute path to this Git repository on your server.
  35     It is expected that this will be a bare repository (ending in
  36       `.git`).
  37
  38  +  **`BUILD_DIRECTORY`**:
  39     In order to access the files when you push, the repository will be
  40       checked out here.
  41     **This directory will be deleted on every push.**
  42
  43  +  **`PUBLIC_DIRECTORY`**:
  44     The directory that your server serves files from.
  45     **This directory will be deleted on every push,** so if you need to
  46       serve additional files (i·e those not generated by this script),
  47       you should place those files in a different directory and adjust
  48       your server configuration accordingly.
  49     Note that the `post-receive` script and associted H·T·M·L files
  50       provided by this repository expect a certain server configuration
  51       described below.
  52
  53   +  **`PUBLIC_URL`**:
  54      The U·R·L that you are serving your site from (with no trailing
  55        slash).
  56      You cannot serve Status.git from a subdirectory.
  57
  58 A `Makefile` is provided to make installing the `post-receive` script
  59   on your server easy (assuming you have `ssh` access).
  60 You’ll need to supply some variables there, too :—
  61
  62  +  **`USERNAME`**:
  63     Your SSH username.
  64
  65  +  **`DOMAIN`**:
  66     The domain or other address of your site.
  67
  68  +  **`GIT_REPOSITORY`**:
  69     The absolute path to this Git repository, as above.
  70
  71 ## Server Configuration
  72
  73 Your server should be configured to serve the following files from the
  74   provided `PUBLIC_DIRECTORY` in response to the following requests :—
  75
  76 ### H·T·M·L responses
  77
  78 These responses **must** be served with a `Content-Type` of
  79   `text/html;charset=UTF-8` (or equivalent).
  80 Note that these paths **do not** have a trailing slash.
  81
  82  +  **`GET /`**:
  83     Serve the file at `/index.html`.
  84
  85  +  **`GET /statuses`**:
  86     Serve the file at `/.statuses.html`.
  87     A `Link` header with the value
  88       `</statuses.jsonld>;rel=meta;type="application/ld+json"` (or
  89       equivalent) **must** be provided.
  90
  91  +  **`GET /$YYYY-MM`** (where `$YYYY-MM` is an `xsd:gYearMonth`):
  92     Serve the file at `/.topic.html`.
  93     A `Link` header with the value
  94       `</$YYYY-MM.jsonld>;rel=meta;type="application/ld+json"` (or
  95       equivalent) **must** be provided.
  96
  97  +  **`GET /$YYYY-MM/*`** (where `$YYYY-MM` is an `xsd:gYearMonth`):
  98     Serve the file at `/.status.html`.
  99     A `Link` header with the value
 100       `</$YYYY-MM.jsonld>;rel=meta;type="application/ld+json"` (or
 101       equivalent) **must** be provided.
 102
 103  +  **`GET /topics`**:
 104     Serve the file at `/.topics.html`.
 105     A `Link` header with the value
 106       `</topics.jsonld>;rel=meta;type="application/ld+json"` (or
 107       equivalent) **must** be provided.
 108
 109  +  **`GET /topics/$TOPIC`** (where `$TOPIC` matches `[0-9A-Za-z_-]+`):
 110     Serve the file at `/.topic.html`.
 111     A `Link` header with the value
 112       `</$TOPIC.jsonld>;rel=meta;type="application/ld+json"` (or
 113       equivalent) **must** be provided.
 114
 115  +  **`GET /topics/$TOPIC/*`** (where `$TOPIC` matches
 116       `[0-9A-Za-z_-]+`):
 117     Serve the file at `/.status.html`.
 118     A `Link` header with the value
 119       `</$TOPIC.jsonld>;rel=meta;type="application/ld+json"` (or
 120       equivalent) **must** be provided.
 121
 122 ### Json‐L·D responses
 123
 124 These responses **should** be served with a `Content-Type` of
 125   `application/ld+json`.
 126 In all cases, for `/$PATH.jsonld`, this just serves the file at
 127   `/$PATH/index.jsonld`.
 128
 129  +  **`GET /statuses.jsonld`**:
 130     Serve the file at `/statuses/index.jsonld`.
 131
 132  +  **`GET /$YYYY-MM.jsonld`** (where `$YYYY-MM` is an
 133       `xsd:gYearMonth`):
 134     Serve the file at `/$YYYY-MM/index.jsonld`.
 135
 136  +  **`GET /topics.jsonld`**:
 137     Serve the file at `/topics/index.jsonld`.
 138
 139  +  **`GET /topics/$TOPIC.jsonld`** (where `$TOPIC` matches
 140       `[0-9A-Za-z_-]+`):
 141     Serve the file at `/topics/$TOPIC/index.jsonld`.
 142
 143 ### Other Headers
 144
 145 All responses **should** have a `Access-Control-Allow-Origin` header
 146   with a value of `*` (assuming your server does not use credentials
 147   and is not being served behind a firewall).
 148
 149 ## Committing Statuses To Git
 150
 151 The `post-receive` script will run whenever you make a commit to the
 152   `live` branch, which should be set as your default.
 153 Statuses are represented by a small collection of files committed to
 154   particular locations in this repository :—
 155
 156  +  Files committed to `/YYYY/MM/DD/HH.MM.SSZ/` (the final component
 157       can actually take any form but a time is **recommended**) are
 158       ordinary statuses.
 159
 160  +  Files committed to `/topic/TOPICNAME/a/b/c/d/xxxx` (where `a`, `b`,
 161       `c`, and `d` are lowercase hexadecimal digits and `xxxx` can be
 162       anything) is a status posted to a specific topic (`TOPICNAME`).
 163     It is **recommended** that you make `a/b/c/d` the first four digits
 164       of an MD5 hash of the status content and `xxxx` the remaining
 165       digits (security is not an issue here, so MD5 is fine).
 166     `TOPICNAME` should have the form `[0-9A-Za-z_-]+`.
 167
 168 The intent is that “ordinary statuses” are a bit more ephemeral whereas
 169   “topic statuses” can serve as reference material.
 170 Using an MD5 hash for topic statuses ensures you don’t post the same
 171   thing twice.
 172
 173 The files which represent a status are as follows :—
 174
 175  +  **`text`**:
 176     The text of the status.
 177     Blank lines separate paragraphs; linebreaks will be preserved.
 178     There is a special markup for links: `<https://link.example>`, or
 179       `<https://link.example>="link text"` if you want to supply link
 180       text.
 181     At present, no other markup is supported.
 182
 183  +  **`0=x_status_git_1.0`**:
 184     This file is **optional** and not currently used for anything, but
 185       indicates that the post follows the `1.0` format.
 186     The contents of this file, if present, **must** be
 187       `x_status_git_1.0`, optionally followed by a trailing newline.
 188
 189  +  **`1=NAME`** (where `NAME` might be anything):
 190     This file is **recommended** and indicates the author of the
 191       status.
 192     Only one author is currently supported.
 193     The value of `NAME` **must** give the name of the author of the
 194       status.
 195     The contents of this file **must** give the author’s URL,
 196       optionally followed by a trailing newline.
 197
 198  +  **`3=YYYY-MM-DD`** (where `YYYY-MM-DD` is a date):
 199     This file is **required** and indicates the date of the status.
 200     Only one date is currently supported.
 201     The value of `YYYY-MM-DD` **should** give the date of the status,
 202       although this is not used (in favour of the full timestamp).
 203     The contents of this file **must** give the full `xsd:dateTime`
 204       timestamp of the status, optionally followed by a trailing
 205       newline.
 206
 207  +  **`4=IDENTIFIER`** (where `IDENTIFIER` might be anything):
 208     This file is **required** and provides an identifier for the
 209       status.
 210     Only one identifier is currently supported.
 211     The contents of this file **must** be an I·R·I which uniquely
 212       identifies the status (for example, a U·U·I·D or `tag:` URI).
 213     The value of `IDENTIFIER` **must** be a locally‐unique identifier
 214       for the status and **should** resemble the contents where
 215       possible.
 216     (Note, however, that `IDENTIFIER` cannot contain slashes and need
 217       not be a valid I·R·I.)
 218
 219 Files with names that begin with the strings `2=` or `x_status_git_`
 220   are reserved for backwards‐compatible extensions.
 221
 222 Status.git has no opinion on how these files make their way into the
 223   Git repository, except that all the files for a single status should
 224   be added in the same commit.
 225 The intention is that the simple nature of these files will make them
 226   easy to automate.
 227
 228 ## I Am Computer, How Do I Get Status?
 229
 230 Assume you are given a U·R·L to a status collection, like `/statuses`,
 231   `/YYYY-MM`, or `/topics/my_topic`.
 232 Make a `HEAD` request to this U·R·L.
 233 If there is a `Link` header with a `rel` of `meta` and a `type` of
 234   `application/ld+json`, make a `GET` request to that U·R·L instead.
 235 Otherwise, make a `GET` request to the U·R·L you were given.
 236
 237 Assuming the U·R·L you were given was valid, you will receive a
 238   Json‐L·D response with a `@type` which is either an
 239   `OrderedCollection` or an `OrderedCollectionPage`.
 240 One of the following will be true :—
 241
 242  +  The response is an `OrderedCollectionPage`.
 243     Its `items` will be an array of statuses, and the `prev` and
 244       `next` properties will give U·R·Ls for previous and next
 245       pages of statuses (if any exist).
 246
 247  +  The response is an `OrderedCollection` with `first` and
 248       `current` properties.
 249     These properies give the U·R·Ls for the first and latest pages
 250       of statuses, which you can fetch and process as above.
 251
 252  +  Otherwise, the `items` property will be an array of every
 253       status in the collection.
 254
 255  >  If you receive a `Collection` instead of an `OrderedCollection`,
 256  >    you are probably looking at a topics listing.
 257  >  You will need to choose a topic from the `items` and then fetch it
 258  >    to receive the list of statuses.
 259
 260 Statuses themselves have the following properties :—
 261
 262  +  **`@id`**:
 263     The identifier of the status.
 264
 265  +  **`created`** [`dcterms:created`]:
 266     The creation date for the status, as an `xsd:dateTime`.
 267
 268  +  **`creator`** [`dcterms:creator`] (optional):
 269     The author of the status, as an object with an `@id` and `name`
 270       [`foaf:name`].
 271
 272  +  **`identifier`** [`dcterms:identifier`]:
 273     An I·R·I which uniquely identifies the status.
 274     This differs from the `@id` in that it is not expected to be
 275       dereferenceable.
 276
 277  +  **`subject`** [`dcterms:subject`] (optional):
 278     The topic of the status, for topic statuses.
 279
 280  +  **`content`** [`sioc:content`]:
 281     The content of the status, as an `rdf:XMLLiteral`.