defines the standards process followed by the XMPP Standards Foundation.
Building XEPs
-------------
You'll need xmllint and xsltproc.
On Ubuntu, you can install them with `sudo apt install libxml2-utils xsltproc`
To build a single XEP as HTML simply run:
make xep-xxxx.html
To build PDFs, you'll need to install [TeXML](http://getfo.org/texml/) (probably
in a Python 2 virtual environment).
You can then build PDFs with:
make xep-xxxx.pdf
To change the output directory, set the variable `OUTDIR`, eg.
OUTDIR=/tmp/xeps make all
For more information try `make help`.
Using Docker
------------
A full set of HTML and PDFs can be generated inside a docker container, with no
dependencies on the host other than Docker itself, and served by nginx in the
container. To build the template `make docker`, to run it `make testdocker`
(serves on http://localhost:3080), and to stop/delete it afterwards `make
stopdocker`
Gardening (Issue triaging by non-editors)
-----------------------------------------
For new PRs, anyone with permission may perform gardening tasks.
The [Go wiki] summarizes "gardening" as:
> the background maintenance tasks done to keep the project healthy & growing &
> nice looking.
In this repo, gardening is mostly triaging issues.
An issue is considered triaged when an editor has been assigned to it.
Untriaged issues that are in need of attention can be found using the following
filter: [`is:open is:pr no:assignee`]
To triage new issues or PRs, see the [Triaging a PR][#triaging-a-pr] section below.
Editor
======
The XMPP Extensions Editor (or, for short, XEP Editor) manages the XMPP
extensions process as defined in XMPP Extension Protocols ([XEP-0001]).
In addition, the XEP Editor functions as the XMPP Registrar as defined in XMPP
Registrar Function ([XEP-0053]).
Read those documents first, since this README focuses on mechanics instead of
philosophy or policy.
All PRs
-------
For all PRs, start by ensuring that the IP release has been signed and that CI
has run and no issues were detected before merging.
Triaging a PR
-------------
If the PR is not touching a XEP, this guide does not apply. If the PR touches
multiple XEPs, go through the steps for each XEP and exit at the first which
applies.
1. Is the PR a ProtoXEP?
1. Does the PR touch existing XEPs? Close as [invalid] and ask the Opener
to split the two things.
2. Add the [ProtoXEP] and [Ready to Merge] labels.
3. Stop.
2. Sanity checks
1. Ensure that all XEPs are mentioned in the title as `XEP-XXXX`. E.g. `XEP-0084, XEP-0123: something`.
2. Continue.
3. Are the changes *for all XEPs* purely editorial?
1. Add the [Editorial Change] and [Ready to Merge] labels.
2. If the PR does not add a revision block, add the [Needs Version Block] label.
3. If the PR adds a revision block and does not only bump the patch-level (third) version number part, add the [Needs Version Block] label and a comment explaining the situation.
4. Stop.
4. Is the XEP **not** in Experimental state?
(Changes to Non—Experimental XEPs need approval by the approving body as
defined in the XEP file itself.)
1. Add the [Needs Council]/[Needs Board] label.
2. Send an email to the council chair and/or announce the PR in [The Council Room].
3. If the PR does not add a revision block, add the [Needs Version Block] label.
4. If the PR adds a revision block and does not bump the minor-level (second) version number part, add the [Needs Version Block] label and a comment explaining the situation.
5. Stop.
5. Is the XEP in Experimental state and the PR opener is not an author of the
XEP?
1. If the PR does not a revision block, add the [Needs Version Block] label.
2. If the PR adds a revision block and does not bump the minor-level (second) version number part, add the [Needs Version Block] label and a comment explaining the situation.
3. If the issue has not been discussed on the standards list *or* if
the authors have not been involved in the discussion *or* the author
has not explicitly ACKed the PR:
1. Make sure the standards@ discussion (if it exists) is linked in the
PR.
2. Add the [Needs Author] label.
3. Stop.
6. Mark the PR as [Ready to Merge].
Discussions
-----------
Technical discussions SHOULD NOT happen in the xeps repository. If you see a
discussion evolve into technical (as opposed to editorial) matters, do the
following (I haven’t tried that myself yet, so feel especially free to improve
the process):
1. Lock the conversation.
2. Copy the technical discussion parts into an email to standards@. My
preferred format for this would be something along the lines of:
Subject: XEP-1234: [insert PR subject here, or something more appropriate]
There was some discussion on the xeps repository an XEP-1234, which got
technical. I moved this discussion to standards@ so that the whole
community is aware of the issue and can participate.
@user1 wrote:
> quote user1 here ...
@user2 wrote:
> quote user2 here ...
Remove clearly editorial discussion and mark the removal with ``[…]``.
3. Add the [Needs List Discussion] label to the PR and link the standards@
thread you just created. Remove other labels (such as [Needs Author]).
4. Monitor the thread; when the discussion is resolved, the PR opener will
usually prepare an update. Unlock the conversation to allow editorial
discussion to continue, if needed. Remove the [Needs List Discussion] label
and re-triage the PR as described above.
**Note:** The locking is mostly used here as a tool to avoid a race
condition, not to exclude people from participating. (It would be
unfortunate if you had to add more comments to your already-sent email.)
Feel free to unlock at some point during the list discussion when you’re
sure that all participants have taken note of the move.
General notes on making changes
-------------------------------
This section has some hints on the python scripts which help you doing the
more tedious tasks of sending emails and properly archiving XEPs.
*Before* you start working on merging a Pull Request:
* Ideally, you have the [xep-attic] repository cloned next to the xeps
repository.
* Before starting to prepare a merge and push, ensure that you have the XEP
metadata up-to-date locally:
$ make build/xeplist.xml
* Make a copy of the metadata:
$ cp build/xeplist.xml tools/old-xeplist.xml
(avoid putting random XML files in the xeps root directory, the build
tooling might mistake them as XEPs; so we put it somewhere else.)
*While* you’re working on a Pull Request:
* Use the lokal docker build to ensure that everything is syntactically
correct. The process is described above in "Using Docker".
When you have *merged* the Pull Request and the change went through to the
webserver (see also the [Docker Build] to track the build progress):
* Send out the emails. First ensure that the new metadata is up-to-date:
$ make build/xeplist.xml
Check that the emails which will be sent are correct (the ``--dry-run``
switch prevents the tool from actually sending emails):
Jonas Schäfer
3 years ago