mirror of
https://github.com/moparisthebest/xeps
synced 2024-08-13 16:53:48 -04:00
Merge branch 'feature/docs' into main
This commit is contained in:
commit
48018afe1b
388
README.md
388
README.md
@ -4,6 +4,9 @@
|
||||
XMPP Extension Protocols (XEPs)
|
||||
===============================
|
||||
|
||||
About
|
||||
-----
|
||||
|
||||
This repository is used to manage work on XMPP Extension Protocols
|
||||
(XEPs), which are the specifications produced by the XMPP Standards
|
||||
Foundation (XSF). See http://xmpp.org/ for details. The rendered
|
||||
@ -11,6 +14,9 @@ documents can be found here:
|
||||
|
||||
https://xmpp.org/extensions/
|
||||
|
||||
Contribution
|
||||
------------
|
||||
|
||||
Please use this repository to raise issues and submit pull requests:
|
||||
|
||||
https://github.com/xsf/xeps/issues
|
||||
@ -19,7 +25,7 @@ https://github.com/xsf/xeps/pulls
|
||||
For in-depth technical discussion, please post to the standards@xmpp.org
|
||||
email list:
|
||||
|
||||
http://mail.jabber.org/mailman/listinfo/standards
|
||||
https://mail.jabber.org/mailman/listinfo/standards
|
||||
|
||||
To submit a new proposal for consideration as a XEP, please read this
|
||||
page:
|
||||
@ -29,387 +35,11 @@ https://xmpp.org/about/standards-process.html#submitting-a-xep
|
||||
[XEP-0001: XMPP Extension Protocols](https://xmpp.org/extensions/xep-0001.html)
|
||||
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.
|
||||
Documentation for Editors is in the [docs](docs/) folder.
|
||||
|
||||
|
||||
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):
|
||||
|
||||
$ ./tools/send-updates.py --dry-run tools/old-xeplist.xml build/xeplist.xml standards@xmpp.org
|
||||
|
||||
(See also the ``--help`` output for more information.)
|
||||
|
||||
Once you’ve verified that the correct emails will be sent, actually send
|
||||
them using (note the missing ``--dry-run`` flag):
|
||||
|
||||
$ ./tools/send-updates.py tools/old-xeplist.xml build/xeplist.xml standards@xmpp.org
|
||||
|
||||
A few tips:
|
||||
|
||||
1. You can also test-send them to your own address by replacing
|
||||
``standards@xmpp.org`` with your own address.
|
||||
2. To avoid having to enter your email account details every time, use a
|
||||
configuration file. Invoke the tool with ``--help`` for more
|
||||
information and ask [jonasw]/[@horazont] if things are still unclear.
|
||||
|
||||
If the tool misbehaves, pester [jonasw]/[@horazont] about it.
|
||||
|
||||
* Don’t forget to archive the new versions of the XEPs. If you have the
|
||||
[xep-attic] cloned next to the xeps repository, you can simply run:
|
||||
|
||||
$ ./tools/archive.py tools/old-xeplist.xml build/xeplist.xml
|
||||
|
||||
Otherwise, you will have to explicitly give the path to the attic:
|
||||
|
||||
$ ./tools/archive.py --attic /path/to/xep-attic/content/ tools/old-xeplist.xml build/xeplist.xml
|
||||
|
||||
(note that the path must point to the ``content`` subdirectory of the
|
||||
[xep-attic].)
|
||||
|
||||
Don’t forget to commit & push the changes to [xep-attic].
|
||||
|
||||
|
||||
New ProtoXEPs
|
||||
-------------
|
||||
|
||||
- Make sure the protoxep is in the `inbox/` tree and has a name that does not
|
||||
start with "xep-" (you may change this or ask the author to change it).
|
||||
- Make sure the version is `0.0.1` and the status is `ProtoXEP` (you may fix
|
||||
this or ask the author to fix it).
|
||||
- You may want to build the protoxep locally and ensure the HTML and PDF look
|
||||
okay.
|
||||
- Merge the PR as described in "Merging a PR". Once the email has been sent,
|
||||
continue here.
|
||||
- Create a card for the protoxep on the [Council Trello] under "Proposed
|
||||
Agendums".
|
||||
- Attach the PR to the card and link the generated HTML.
|
||||
- Comment on the PR with a link to the card, thanking the author for their
|
||||
submission and letting them know that their XEP will be voted on within the
|
||||
next two weeks.
|
||||
- If the council forgets and doesn't vote on the protoxep, pester them until
|
||||
they do.
|
||||
- If the council rejects the XEP, you're done (leave the XEP in the inbox and
|
||||
inform the author of the councils decision). Otherwise, see
|
||||
"Promoting a ProtoXEP".
|
||||
|
||||
|
||||
Promoting a ProtoXEP
|
||||
--------------------
|
||||
|
||||
- It is easiest to start a new branch, in case you screw something up on the way.
|
||||
- Once the council approves a ProtoXEP, *copy* it out of the inbox and into the
|
||||
root, assigning it the next available number in the XEP series.
|
||||
- Modify the `<number/>` element in the XML file to match.
|
||||
- Set the version to `0.1` and the initials to `XEP Editor: xyz` (replacing "xyz" with your own initials).
|
||||
- Remove the `<interim/>` element from the XML file if it is included.
|
||||
- Set the status to `Experimental`.
|
||||
- Add a reference to the XEP in `xep.ent`.
|
||||
- Make a commit.
|
||||
- Treat your branch as you would treat a [Ready to Merge] PR in "Merging a PR".
|
||||
(you don’t need to create another branch though.)
|
||||
|
||||
|
||||
Promoting XEPs
|
||||
--------------
|
||||
|
||||
Ensure that the following sections exist (if not, ask the author to add them
|
||||
before promoting the XEP):
|
||||
|
||||
- Security Considerations
|
||||
- IANA Considerations
|
||||
- XMPP Registrar Considerations
|
||||
- XML Schema (for protocol specifications)
|
||||
|
||||
You can also refer to `xep-template.xml` for a recommended list of sections and
|
||||
whether or not they are required.
|
||||
For a helpful graph of how XEP promotion works, see [XEP-0001].
|
||||
|
||||
|
||||
Deferring XEPs
|
||||
--------------
|
||||
|
||||
Before Deferring XEPs, read the "General notes on making changes" section.
|
||||
|
||||
XEPs get deferred after 12 months of inactivity. There is a tool which handles
|
||||
that process automatically, if it is invoked regularly.
|
||||
|
||||
First of all, you need an up-to-date ``xeplist.xml``:
|
||||
|
||||
make build/xeplist.xml
|
||||
|
||||
To get a list of XEPs which need to be deferred (without changing anything),
|
||||
run:
|
||||
|
||||
./tools/deferrals.py -v
|
||||
|
||||
To apply the deferrals, make a new feature branch and execute:
|
||||
|
||||
./tools/deferrals.py -m 'initials'
|
||||
|
||||
where you replace ``initials`` with your editor initials so that it is obvious
|
||||
who made the change (those initials will be used in the revision block).
|
||||
|
||||
This will modify the XEPs in-place. It uses heuristics for incrementing the
|
||||
version number, finding and inserting the revision block as well as changing
|
||||
the status. Yes, it involves regular expressions (because we don’t want to
|
||||
fully re-write the XML to keep the diffs minimal). It is thus vital that you
|
||||
**use `git diff` to ensure that the changes are sane**. If the changes
|
||||
are sane, make a commit and merge to master as described in "Merging a PR",
|
||||
in accordance with the "General notes on making changes".
|
||||
|
||||
|
||||
Merging a PR
|
||||
------------
|
||||
|
||||
Before Merging a PR, read the "General notes on making changes" section.
|
||||
|
||||
When you get to the point that the PR is [Ready to Merge], do the following:
|
||||
|
||||
1. Create a new branch off master called ``feature/xep-1234`` (if the PR
|
||||
touches multiple XEPs, I call it ``feature/xep-0678,xep-0789``).
|
||||
|
||||
2. Merge all [Ready to Merge] PRs which affect the XEP(s) into that branch.
|
||||
|
||||
3. Resolve conflicts.
|
||||
|
||||
4. If the PRs introduced multiple revision blocks, squash it down to a single
|
||||
revision block. Set "XEP Editor (initials)" as author of the revision block
|
||||
and add the initials of the original PR authors to the changelog entries.
|
||||
(If that doesn’t make sense to you, you’ll find plenty examples in the
|
||||
XEPs.)
|
||||
|
||||
5. Ensure that everything builds by performing a full docker build (see above).
|
||||
|
||||
(Once the docker build reaches the point where the XEPs are built, you can
|
||||
switch branches and work on another PR.)
|
||||
|
||||
6. If the build passes, check that the generated files look sane by running the
|
||||
docker container.
|
||||
|
||||
7. Merge the PR into master. If you are working on independent changes to
|
||||
multiple XEPs, you can merge them all in one go.
|
||||
|
||||
8. If you merged multiple things into master, re-do the docker build check.
|
||||
|
||||
9. Push.
|
||||
|
||||
10. Go back to "General notes on making changes".
|
||||
|
||||
|
||||
|
||||
[XEP-0001]: https://xmpp.org/extensions/xep-0001.html
|
||||
[XEP-0053]: https://xmpp.org/extensions/xep-0053.html
|
||||
[Editor Trello]: https://trello.com/b/gwcOFnCr
|
||||
[Council Trello]: https://trello.com/b/ww7zWMlI
|
||||
[Needs Council]: https://github.com/xsf/xeps/labels/Needs%20Council
|
||||
[Needs Board]: https://github.com/xsf/xeps/labels/Needs%20Board
|
||||
[ProtoXEP]: https://github.com/xsf/xeps/labels/ProtoXEP
|
||||
[Go wiki]: https://golang.org/wiki/Gardening
|
||||
[`is:open is:pr no:assignee`]: https://github.com/xsf/xeps/pulls?utf8=%E2%9C%93&q=is%3Aopen%20is%3Apr%20no%3Aassignee%20
|
||||
[Needs Author]: https://github.com/xsf/xeps/labels/Needs%20Author
|
||||
[Ready to Merge]: https://github.com/xsf/xeps/labels/Ready%20to%20Merge
|
||||
[Needs List Discussion]: https://github.com/xsf/xeps/labels/Needs%20List%20Discussion
|
||||
[Needs Version Block]: https://github.com/xsf/xeps/labels/Needs%20Version%20Block
|
||||
[Editorial Change]: https://github.com/xsf/xeps/labels/Editorial%20Change
|
||||
[xep-attic]: https://github.com/xsf/xep-attic
|
||||
[Docker Build]: https://hub.docker.com/r/xmppxsf/xeps/builds/
|
||||
[@horazont]: https://github.com/horazont/
|
||||
[jonasw]: https://wiki.xmpp.org/web/User:Jwi
|
||||
[The Council Room]: xmpp:council@muc.xmpp.org?join
|
||||
|
||||
[modeline]: # ( vim: set fenc=utf-8 ff=unix spell spl=en textwidth=80: )
|
||||
|
39
docs/MODERATION.md
Normal file
39
docs/MODERATION.md
Normal file
@ -0,0 +1,39 @@
|
||||
# Moderation
|
||||
|
||||
## 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:
|
||||
|
||||
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: [insert PR title 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.
|
203
docs/PROCESSING.md
Normal file
203
docs/PROCESSING.md
Normal file
@ -0,0 +1,203 @@
|
||||
# Processing a PR
|
||||
|
||||
## 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 local docker build to ensure that everything is syntactically
|
||||
correct. The process is described above in "Using Docker".
|
||||
|
||||
### After merging the Pull Request
|
||||
|
||||
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):
|
||||
|
||||
$ ./tools/send-updates.py --dry-run tools/old-xeplist.xml build/xeplist.xml standards@xmpp.org
|
||||
|
||||
(See also the ``--help`` output for more information.)
|
||||
|
||||
Once you’ve verified that the correct emails will be sent, actually send
|
||||
them using (note the missing ``--dry-run`` flag):
|
||||
|
||||
$ ./tools/send-updates.py tools/old-xeplist.xml build/xeplist.xml standards@xmpp.org
|
||||
|
||||
A few tips:
|
||||
|
||||
1. You can also test-send them to your own address by replacing
|
||||
``standards@xmpp.org`` with your own address.
|
||||
2. To avoid having to enter your email account details every time, use a
|
||||
configuration file. Invoke the tool with ``--help`` for more
|
||||
information and ask [jonas’]/[@horazont] if things are still unclear.
|
||||
|
||||
If the tool misbehaves, pester [jonas’]/[@horazont] about it.
|
||||
|
||||
* Don’t forget to archive the new versions of the XEPs. If you have the
|
||||
[xep-attic] cloned next to the xeps repository, you can simply run:
|
||||
|
||||
$ ./tools/archive.py tools/old-xeplist.xml build/xeplist.xml
|
||||
|
||||
Otherwise, you will have to explicitly give the path to the attic:
|
||||
|
||||
$ ./tools/archive.py --attic /path/to/xep-attic/content/ tools/old-xeplist.xml build/xeplist.xml
|
||||
|
||||
(note that the path must point to the ``content`` subdirectory of the
|
||||
[xep-attic].)
|
||||
|
||||
Don’t forget to commit & push the changes to [xep-attic].
|
||||
|
||||
|
||||
## New ProtoXEPs
|
||||
|
||||
- Make sure the protoxep is in the `inbox/` tree and has a name that does not
|
||||
start with "xep-" (you may change this or ask the author to change it).
|
||||
- Make sure the version is `0.0.1` and the status is `ProtoXEP` (you may fix
|
||||
this or ask the author to fix it).
|
||||
- You may want to build the protoxep locally and ensure the HTML and PDF look
|
||||
okay.
|
||||
- Merge the PR as described in "Merging a PR". Once the email has been sent,
|
||||
continue here.
|
||||
- Create a card for the protoxep on the [Council Trello] under "Proposed
|
||||
Agendums".
|
||||
- Attach the PR to the card and link the generated HTML.
|
||||
- Comment on the PR with a link to the card, thanking the author for their
|
||||
submission and letting them know that their XEP will be voted on within the
|
||||
next two weeks.
|
||||
- If the council forgets and doesn't vote on the protoxep, pester them until
|
||||
they do.
|
||||
- If the council rejects the XEP, you're done (leave the XEP in the inbox and
|
||||
inform the author of the councils decision). Otherwise, see
|
||||
"Promoting a ProtoXEP".
|
||||
|
||||
|
||||
## Promoting a ProtoXEP to Experimental
|
||||
|
||||
- It is easiest to start a new branch, in case you screw something up on the way.
|
||||
- Once the council approves a ProtoXEP, *copy* it out of the inbox and into the
|
||||
root, assigning it the next available number in the XEP series.
|
||||
- Modify the `<number/>` element in the XML file to match.
|
||||
- Set the version to `0.1` and the initials to `XEP Editor: xyz` (replacing "xyz" with your own initials).
|
||||
- Remove the `<interim/>` element from the XML file if it is included.
|
||||
- Set the status to `Experimental`.
|
||||
- Add a reference to the XEP in `xep.ent`.
|
||||
- Make a commit.
|
||||
- Treat your branch as you would treat a [Ready to Merge] PR in "Merging a PR".
|
||||
(you don’t need to create another branch though.)
|
||||
|
||||
|
||||
## Promoting XEPs beyond Experimental
|
||||
|
||||
Ensure that the following sections exist (if not, ask the author to add them
|
||||
before promoting the XEP):
|
||||
|
||||
- Security Considerations
|
||||
- IANA Considerations
|
||||
- XMPP Registrar Considerations
|
||||
- XML Schema (for protocol specifications)
|
||||
|
||||
You can also refer to `xep-template.xml` for a recommended list of sections and
|
||||
whether or not they are required.
|
||||
For a helpful graph of how XEP promotion works, see [XEP-0001].
|
||||
|
||||
|
||||
## Deferring XEPs
|
||||
|
||||
Before Deferring XEPs, read the "General notes on making changes" section.
|
||||
|
||||
XEPs get deferred after 12 months of inactivity. There is a tool which handles
|
||||
that process automatically, if it is invoked regularly.
|
||||
|
||||
First of all, you need an up-to-date ``xeplist.xml``:
|
||||
|
||||
make build/xeplist.xml
|
||||
|
||||
To get a list of XEPs which need to be deferred (without changing anything),
|
||||
run:
|
||||
|
||||
./tools/deferrals.py -v
|
||||
|
||||
To apply the deferrals, make a new feature branch and execute:
|
||||
|
||||
./tools/deferrals.py -m 'initials'
|
||||
|
||||
where you replace ``initials`` with your editor initials so that it is obvious
|
||||
who made the change (those initials will be used in the revision block).
|
||||
|
||||
This will modify the XEPs in-place. It uses heuristics for incrementing the
|
||||
version number, finding and inserting the revision block as well as changing
|
||||
the status. Yes, it involves regular expressions (because we don’t want to
|
||||
fully re-write the XML to keep the diffs minimal). It is thus vital that you
|
||||
**use `git diff` to ensure that the changes are sane**. If the changes
|
||||
are sane, make a commit and merge to master as described in "Merging a PR",
|
||||
in accordance with the "General notes on making changes".
|
||||
|
||||
|
||||
## Merging a PR
|
||||
|
||||
Before Merging a PR, read the "General notes on making changes" section.
|
||||
|
||||
When you get to the point that the PR is [Ready to Merge], do the following:
|
||||
|
||||
1. Create a new branch off master called ``feature/xep-1234`` (if the PR
|
||||
touches multiple XEPs, I call it ``feature/xep-0678,xep-0789``).
|
||||
|
||||
2. Merge all [Ready to Merge] PRs which affect the XEP(s) into that branch.
|
||||
|
||||
3. Resolve conflicts.
|
||||
|
||||
4. If the PRs introduced multiple revision blocks, squash it down to a single
|
||||
revision block. Set "XEP Editor (initials)" as author of the revision block
|
||||
and add the initials of the original PR authors to the changelog entries.
|
||||
(If that doesn’t make sense to you, you’ll find plenty examples in the
|
||||
XEPs.)
|
||||
|
||||
5. Ensure that everything builds by performing a full docker build (see above).
|
||||
|
||||
(Once the docker build reaches the point where the XEPs are built, you can
|
||||
switch branches and work on another PR.)
|
||||
|
||||
6. If the build passes, check that the generated files look sane by running the
|
||||
docker container.
|
||||
|
||||
7. Merge the PR into master. If you are working on independent changes to
|
||||
multiple XEPs, you can merge them all in one go.
|
||||
|
||||
8. If you merged multiple things into master, re-do the docker build check.
|
||||
|
||||
9. Push.
|
||||
|
||||
10. Go back to "General notes on making changes".
|
||||
|
||||
[XEP-0001]: https://xmpp.org/extensions/xep-0001.html
|
||||
[Ready to Merge]: https://github.com/xsf/xeps/labels/Ready%20to%20Merge
|
||||
[Council Trello]: https://trello.com/b/ww7zWMlI
|
||||
[xep-attic]: https://github.com/xsf/xep-attic
|
||||
[Docker Build]: https://hub.docker.com/r/xmppxsf/xeps/builds/
|
||||
[@horazont]: https://github.com/horazont/
|
||||
[jonas’]: https://wiki.xmpp.org/web/User:Jwi
|
39
docs/README.md
Normal file
39
docs/README.md
Normal file
@ -0,0 +1,39 @@
|
||||
Editor Guide
|
||||
============
|
||||
|
||||
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.
|
||||
|
||||
|
||||
This is the entrypoint definitive guide for Editors.
|
||||
|
||||
- [Using the repository](REPOSITORY.md)
|
||||
|
||||
Information about how to build XEPs and how the repository is laid out.
|
||||
|
||||
<!--
|
||||
- [Tools](TOOLS.md)
|
||||
|
||||
Information about tools provided with the repository which should help in
|
||||
your daily editor duties.
|
||||
-->
|
||||
|
||||
- [Triaging](TRIAGING.md)
|
||||
|
||||
Rules for labelling and guiding inbound Pull Requests (Merge Requests).
|
||||
|
||||
- [Processing](PROCESSING.md)
|
||||
|
||||
Rules and guidelines for processing inbound Pull Requests (Merge Requests)
|
||||
towards master/main.
|
||||
|
||||
- [Moderation](MODERATION.md)
|
||||
|
||||
Rules and guidelines for moderating the discussions in the PRs.
|
||||
|
||||
|
||||
[XEP-0053]: https://xmpp.org/extensions/xep-0053.html
|
34
docs/REPOSITORY.md
Normal file
34
docs/REPOSITORY.md
Normal file
@ -0,0 +1,34 @@
|
||||
Using the repository
|
||||
====================
|
||||
|
||||
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`
|
154
docs/TRIAGING.md
Normal file
154
docs/TRIAGING.md
Normal file
@ -0,0 +1,154 @@
|
||||
# Triaging a PR
|
||||
|
||||
## Dramatis Personae
|
||||
|
||||
- Author: Generally the author of the PR or MR.
|
||||
- XEP Author: The Author of the XEP.
|
||||
- Approving Body: Either the XMPP Council or the XSF Board. Which of those two
|
||||
can be determined by looking at the `<approver/>` tag of the respective XEP.
|
||||
- Processing Editor: The Editor which ultimately merges a PR to master.
|
||||
|
||||
## Labels
|
||||
|
||||
### Approval categories
|
||||
|
||||
- [Needs Council]: The changes need approval by the XMPP Council.
|
||||
- [Needs Board]: The changes need approval by the XSF Board.
|
||||
- [Needs Author]: The changes need approval by the XEP Author.
|
||||
- [Needs List Discussion]: The changes need more discussion on the standards@
|
||||
(or, in rare cases, members@) mailing lists; in general, there should be a
|
||||
link to a mailing list thread in those PRs.
|
||||
- [Editorial Change]: The changes do not need approval by anyone except the
|
||||
Editor.
|
||||
|
||||
### Process categories
|
||||
|
||||
- [ProtoXEP]: The PR adds a new XEP to the inbox.
|
||||
- [Ready to Merge]: The PR can be worked on by a Processing Editor. Note that
|
||||
this does **not** imply that no further changes are needed.
|
||||
- [Needs Version Block]: A version block needs to be added or modified before
|
||||
the changes can enter master.
|
||||
- [Needs Editor Action]: The Processing Editor needs to do something while
|
||||
merging the PR, aside of or in addition to modifying a version block.
|
||||
- [invalid]: The changes cannot be processed as-is at all; the PR is closed
|
||||
without merge and without being handed to an approver.
|
||||
|
||||
## Process
|
||||
|
||||
### A General Note
|
||||
|
||||
Some of the cases where the below process suggests to ask the Author to do
|
||||
something can also be handled by the Processing Editor. If it is realistic
|
||||
that the workload for the Editors would be reduced by handling the task
|
||||
themselves, use the [Needs Editor Action] label an an explanatory comment
|
||||
instead.
|
||||
|
||||
### "Flowchart"
|
||||
|
||||
If the PR is not touching a XEP, this guide does not apply.
|
||||
|
||||
1. Is the PR a ProtoXEP?
|
||||
|
||||
1. Does the PR touch existing XEPs? Close as [invalid] and ask the Author
|
||||
to split the two things.
|
||||
|
||||
2. Validate that the `<type/>` makes sense for the content (consult
|
||||
[XEP-0001] if necessary). If it does not make sense, either add a
|
||||
comment to let the Processing Editor know (adding the
|
||||
[Needs Editor Action] label) or ask the Author to correct the problem.
|
||||
3. Add the [ProtoXEP] and [Ready to Merge] labels.
|
||||
4. Make sure the title of the PR is `XEP-XXXX: Title of the new XEP`.
|
||||
5. 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?
|
||||
|
||||
Editorial changes are changes which do not touch normative language and
|
||||
which do not change the meaning of the text. When in doubt, treat as
|
||||
non-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. Does the PR touch more than one XEP?
|
||||
|
||||
In general, we want to avoid PRs which touch multiple XEPs or which do
|
||||
multiple non-Editorial changes at once. This is because the approving body
|
||||
may disagree with part of the PR, which causes extra work.
|
||||
|
||||
Suggest the author to split the PR for that reason, unless it seems
|
||||
realistic or obvious that the changes need to be done together to make
|
||||
sense (an example is updating multiple XEPs which belong together, such
|
||||
as the MIX family).
|
||||
|
||||
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. To know which, check the
|
||||
`<approver/>` of the XEPs. If the touched XEPs have different approvers
|
||||
go back to the previous step and closely examine if the PR should not
|
||||
be split; it is very likely that it should be split in this situation.
|
||||
If so, tag as [invalid] and inform the author, asking them to do a
|
||||
split.
|
||||
2. **For Council:** Send an email to the council chair and/or announce the
|
||||
PR in [The Council Room].
|
||||
**For Board:** Send an email to info@xmpp.org and/or talk directly to
|
||||
Board members.
|
||||
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 for the next Editor (the Author does
|
||||
not need to do anything here).
|
||||
5. Stop.
|
||||
|
||||
5. Is the XEP in Experimental state and the PR opener is not an author of the
|
||||
XEP?
|
||||
|
||||
Changes to Experimental XEPs are approved by the XEP Authors themselves.
|
||||
If the PR touches multiple XEPs and the XEP Authors do not overlap, ask
|
||||
the Author to split the PR.
|
||||
|
||||
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 for the Processing Editor.
|
||||
3. If the issue has not been discussed on the standards list *or* if
|
||||
the XEP Author has not been involved in the discussion *or* the
|
||||
XEP 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. Try to make the XEP Author aware of the change. If you do not know
|
||||
a GitHub handle of the XEP Author, use the contact info available
|
||||
for each author in either the XEP or in xep.ent.
|
||||
4. Stop.
|
||||
|
||||
4. Otherwise, mark the PR as [Ready to Merge], linking the XEP Author’s
|
||||
approval for documentation purposes.
|
||||
|
||||
6. Mark the PR as [Ready to Merge].
|
||||
|
||||
[ProtoXEP]: https://github.com/xsf/xeps/labels/ProtoXEP
|
||||
[Ready to Merge]: https://github.com/xsf/xeps/labels/Ready%20to%20Merge
|
||||
[Needs Author]: https://github.com/xsf/xeps/labels/Needs%20Author
|
||||
[Needs List Discussion]: https://github.com/xsf/xeps/labels/Needs%20List%20Discussion
|
||||
[Needs Version Block]: https://github.com/xsf/xeps/labels/Needs%20Version%20Block
|
||||
[Needs Editor Action]: https://github.com/xsf/xeps/labels/Needs%20Editor%20Action
|
||||
[Editorial Change]: https://github.com/xsf/xeps/labels/Editorial%20Change
|
||||
[Needs Council]: https://github.com/xsf/xeps/labels/Needs%20Council
|
||||
[Needs Board]: https://github.com/xsf/xeps/labels/Needs%20Board
|
||||
[invalid]: https://github.com/xsf/xeps/labels/invalid
|
Loading…
Reference in New Issue
Block a user