From cf421f9217d6c8f1ce67db81cb7a72c455aec367 Mon Sep 17 00:00:00 2001
From: "Juan J. Martinez" <jjm@usebox.net>
Date: Sat, 4 May 2024 16:22:42 +0100
Subject: Moved to self-hosting

- add a tool to generate a release feed (atom)
- add a doc on how to contribute
- update README
---
 CONTRIBUTING.md |  36 +++++++++++++++++++
 README.md       |   2 +-
 tools/atom.py   | 106 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 143 insertions(+), 1 deletion(-)
 create mode 100644 CONTRIBUTING.md
 create mode 100755 tools/atom.py

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..16b429d
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,36 @@
+# Contributing
+
+This document explains how to contribute to this project using email.
+
+## Sending patches
+
+Please submit patches to `<patches@usebox.net>`. The preferred way to do that is [git send-email](https://git-scm.com/docs/git-send-email) (see [this step-by-step guide](https://git-send-email.io/) for more information).
+
+Alternatively, you can push your changes to a public repository, for example hosted on your own Git server, on Sourcehut, Gitlab or GitHub, and use [git request-pull](https://git-scm.com/docs/git-request-pull) to send a pull request.
+
+If these options don't work for you, just use your mail client to send a mail with a link to your changes and a short description.
+
+### Example: git send-email
+
+This example shows how to prepare a patch. First you have to check out the Git repository and configure the destination email address and the subject prefix:
+
+```
+$ git clone https://git.usebox.net/ubox-msx-lib && cd ubox-msx-lib
+$ git config sendemail.to "patches@usebox.net"
+$ git config format.subjectPrefix "PATCH ubox-msx-lib"
+```
+
+Then you can make and commit your changes.
+
+Finally use `git send-email` to generate a patch for the last commit and send it:
+
+```
+$ git send-email HEAD^
+```
+
+This example assumes that you have already configured [git send-email](https://git-scm.com/docs/git-send-email) for sending mails.
+
+## Contact
+
+Feel free to [contact me](https://www.usebox.net/jjm/about/me/) for questions or to discuss big changes in advance.
+
diff --git a/README.md b/README.md
index 301e856..aa26884 100644
--- a/README.md
+++ b/README.md
@@ -128,7 +128,7 @@ Some advice if you want to make a successful contribution:
 
  - Be cordial
  - Get early feedback, specially when working on a large contribution
- - Contributions always require a pull request and a review
+ - Read [CONTRIBUTING](CONTRIBUTING.md)
  - Check the [TODO](TODO.md) for ideas!
 
 ### Formatting
diff --git a/tools/atom.py b/tools/atom.py
new file mode 100755
index 0000000..1a174f7
--- /dev/null
+++ b/tools/atom.py
@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+
+# script to generate an atom feed from CHANGES.md
+
+import re
+from datetime import datetime, timezone, time
+
+release = re.compile("^## Release ([0-9]+\\.[0-9]+\\.[0-9]+) - ([0-9]+-[0-9]+-[0-9]+)$")
+
+title = "ubox MXS lib releases"
+base_url = "https://www.usebox.net/jjm/ubox-msx-lib/changes.html"
+release_url = "https://git.usebox.net/ubox-msx-lib/tag/"
+feed_file = "releases.xml"
+author = "jjm"
+tz = timezone.utc
+
+
+def get_entries(changes):
+    entries = []
+
+    with open(changes, "rt") as fd:
+        lines = fd.readlines()
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        m = release.match(line)
+        if m:
+            version = m.group(1)
+            # because timezones and summer time, use 1am
+            updated_on = datetime.combine(
+                datetime.fromisoformat(m.group(2)), time(1, 0, 0)
+            ).astimezone(tz)
+            body = ""
+            i += 1
+            while i < len(lines) and (lines[i] == "" or lines[i][0] != "#"):
+                body += lines[i]
+                i += 1
+
+            entries.append(dict(version=version, updated_on=updated_on, body=body))
+        else:
+            i += 1
+
+    entries.sort(key=lambda o: o["updated_on"], reverse=True)
+    return entries
+
+
+def to_atom(post):
+    return """\
+<entry>
+    <title>{title}</title>
+    <link rel="alternate" href="{url}"/>
+    <id>{url}</id>
+    <updated>{updated_on}</updated>
+    <content type="xhtml">
+      <div xmlns="http://www.w3.org/1999/xhtml">
+      <pre>{body}</pre>
+      <p>Download available at <a href="{release_url}?h={version}">ubox MSX lib website</a>.</p>
+      </div>
+    </content>
+</entry>\n""".format(
+        title="Released ubox MSX lib " + post["version"],
+        url=base_url + "#release-" + post["version"] + "---" + post["updated_on"].date().isoformat(),
+        version=post["version"],
+        release_url=release_url,
+        updated_on=post["updated_on"].isoformat(),
+        body=post["body"].rstrip() + "\n",
+    )
+
+
+def gen_atom(entries):
+
+    updated_on = datetime(1900, 1, 1, tzinfo=tz)
+    posts_atom = []
+    for post in entries:
+        if post["updated_on"] > updated_on:
+            updated_on = post["updated_on"]
+
+        posts_atom.append(to_atom(post))
+
+    return "\n".join(
+        [
+            """<?xml version="1.0" encoding="utf-8"?>""",
+            """<feed xmlns="http://www.w3.org/2005/Atom">""",
+            """<title>%s</title>""" % title,
+            """<link href="%s"/>""" % base_url,
+            """<link rel="self" href="%s"/>""" % (base_url + feed_file),
+            """<updated>%s</updated>""" % updated_on.isoformat(),
+            """<id>%s</id>""" % base_url,
+            """<author>""",
+            """    <name>%s</name>""" % author,
+            """</author>""",
+        ]
+        + posts_atom
+        + ["</feed>"]
+    )
+
+
+def main():
+    entries = get_entries("../CHANGES.md")
+    with open(feed_file, "wt") as fd:
+        fd.write(gen_atom(entries))
+
+
+if __name__ == "__main__":
+    main()
-- 
cgit v1.2.3