diff --git a/README.md b/README.md index 4e49c757..2d70f5fc 100644 --- a/README.md +++ b/README.md @@ -50,4 +50,128 @@ 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` +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 +--------- + +For new PRs, anyone with permission may perform gardening tasks. +The [Go wiki] sumarizes "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: + +- Is the issue a duplicate? Close it (referencing the original issue). +- Is the issue a question and not an issue? Close it, pointing them at the + mailing list or chat room. +- Is the PR a new ProtoXEP? Add the "[ProtoXEP]" label and ensure that the + file is in the "inbox/" tree and does not start with "xep-" (if not, leave a + comment asking for it to be moved). +- Is the issue a specific change to an existing XEP or a few XEPs (eg. not + whitespace changes to many XEPs, use your judgement)? Make sure the title + starts with "XEP-XXXX:" or "XEP-XXXX, XEP-YYYY:". +- Finally, assign an editor (pick one at random, or pick the one with the least + issues already assigned to them; we may re-assign it later so don't feel bad). + The list of active editors can be found here: + https://xmpp.org/about/xsf/editor-team + + +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. + + +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. +- Create a card for the protoxep on the [Council Trello] under "Proposed + Agendums". +- Attach the PR to the card, and 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. +- Merge the PR and add a link to the generated protoxep (does this happen + automatically yet?) to the card so that council can read it. +- Wait for the XEP to appear on xmpp.org and then log into the webserver, change + directories to `/home/xsf/xmpp-hg/extensions`, perform an `hg pull && hg + update` (yes, that's right) and run `inxep.py name approvingbody` (eg. + `./inxep.py pars council`). +- 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 +-------------------- + +- Once the council approves a ProtoXEP, move it out of the inbox and into the + root, assigning it the next available number in the XEP series. +- Modify the `` 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 `` element from the XML file if it is included. +- Set the status to `Experimental`. +- Add a reference to the XEP in `xep.ent`. +- Archive the first version of the XEP (TODO: this process is currently + changing; add a description when the dust has settled). +- Wait for the XEP to be published then log into the webserver and run + `announce.py` (TODO: Add an example here). + + +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]. + +[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 +[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 + +[modeline]: # ( vim: set fenc=utf-8 ff=unix spell spl=en textwidth=80: )