Open horazont opened 1 year ago
I would like to propose an alternative to this, which would hopefully be much easier to do.
If I understand correctly, we basically want historical versions of XEPs, the attic is what we currently call this. But this is highly brittle, because we are trying to create our own transactional system instead of using a database or git, but we already have git, and developers looking at XEPs are already used to the concept of history etc, so I think what we really want is just a way to view historical XEPs ?
Just like how with anything else I'd go to https://github.com/xsf/xeps/blob/master/xep-0368.xml and click "commit" and then "parent" or "history" and then click to look at past versions? Except we'd want these rendered as XEPs right? Why not just write a tool to do exactly this, using git? Possibly even taking gitea/cgit/rgit and just adding a xep-rendering-extension similar to how they render markdown now? Or go through history and using xep2md create a git repo with the same history except XEPs are markdown and then github will render them for free for us?
tl;dr find a way to use existing git viewing tools to solve the attic for us
Do any of those sound acceptable? I understand this slight process change may require Board approval but I can't imagine they'd have a problem with it.
While this helps with viewing, it doesn't help with automating the email sending process, does it?
Summary
Many actions the editor do involve sending or processing diffs (= changes before and after an editor action). For instance, when updating a XEP, the editor will generally send an update email which informs the community about the changes.
There is tooling which analyses the current state of a
xeps
repository checkout and dumps it in a machine-readable format (make build/xeplist.xml
). There are also various tools which act on this state or on the difference between two such states (tools/archive.py
,tools/send-updates.py
).The challenge in the context of automation is to know the "old" and the "new" state to base the comparison on.
Concept
Conceptually, this requires that the XEP tooling knows about changes which have been formally "published". "Published" changes have been announced to the mailing list and archived into the attic.
Note that "Published" is not equivalent to changes being in the main branch of the git repository.
Requirements
We don't yet know what such a system should look like, so instead of concrete steps to implement it, here are the requirements:
MUST allow running downstream tools on each transaction, passing the "published" and "unpublished" state in form of a
xeplist.xml
file into it.The goal here is to use this system to run
tools/archive.py
andtools/send-updates.py
, and potential future tools.MUST allow a dry-run functionality
During a dry-run, changes MUST NOT be marked as published and downstream tools should be informed in some to-be-defined way that they are in a dry-run situation (preferably environment variable).
MUST NOT mark changes as published if any of the dependent tools fail to run
Example: If the
archive.py
tool crashes on a diff between commitsA
andB
,B
MUST be processed again in the future and MUST NOT be marked as "seen" by the system.MUST NOT batch multiple changes to the same document into the same transaction
Example: Between the previously published state of the repository and the next run of the tool, XEP-1234 gets updated to 1.0.0 and then to 1.1.0. The tooling MUST handle the transitions to 1.0.0 and 1.1.0 separately.
SHOULD NOT send duplicate emails for the same revision
This may happen depending on how the previous requirements are satisfied, but SHOULD be avoided if possible.
SHOULD ignore any changes not covered by
xeplist.xml
Additional Notes