forked from pEp.foundation/internet-drafts
105 lines
3.2 KiB
Plaintext
105 lines
3.2 KiB
Plaintext
Contents
|
|
========
|
|
|
|
This repository contains different p≡p Internet-Drafts -- some already
|
|
submitted in different versions, others under development and yet to
|
|
be submitted in a first version -- to the IETF Internet-Drafts repository:
|
|
|
|
https://www.ietf.org/id-info/
|
|
|
|
In each directory an Internet-Draft (I-D) is provided, these for now being:
|
|
|
|
* pep (pEp's general draft)
|
|
* pep-email (pEp with email)
|
|
* pep-handshake (pEp's method to authenticate peers)
|
|
* pep-keysync (pEp's method to synchronize secret keys)
|
|
* pep-rating (pEp's rating system to signal privacy levels)
|
|
* pep-trustwords (pEp's replacement for fingerprints)
|
|
|
|
Tools
|
|
=====
|
|
|
|
The mandatory ASCII or XML files for submission are created using
|
|
the kramdown-rfc2629 tool creating the XMLv2 format initially described as
|
|
RFC2629 (obsoleted by RFC7749):
|
|
|
|
https://tools.ietf.org/html/rfc7749
|
|
|
|
Please install kramdown-rfc2629, ruby and xml2rfc through your package
|
|
system or directly from the respective sites:
|
|
|
|
* https://github.com/cabo/kramdown-rfc2629
|
|
* https://www.ruby-lang.org/
|
|
* https://xml2rfc.tools.ietf.org/
|
|
|
|
You can also also install kramdown-rfc2629 through the ruby gem
|
|
packaging system if your packaging system doesn't know anything
|
|
about this tool:
|
|
|
|
https://rubygems.org/
|
|
|
|
Structure and contents of each I-D
|
|
==================================
|
|
|
|
Each p≡p I-D consists of the following raw files:
|
|
|
|
* ${name_of_the_draft}.mkd
|
|
* Makefile
|
|
|
|
Abstracts should give a rough overview of what the I-D is about: this is to
|
|
happen over 5-10 lines. Less than 3 and more than 20 lines should be avoided.
|
|
|
|
The main content goes into the middle section: make sure you also provide
|
|
"Introduction" and "Security Consideration" subsections. For the latter,
|
|
please check RFC3552 to see what aspects to consider:
|
|
|
|
https://tools.ietf.org/html/rfc3552
|
|
|
|
A back section can be used for appendix information like listings or
|
|
information which provides additional information, but which is not
|
|
mandatory to understand the I-D.
|
|
|
|
Basic metadata (e.g., authors' names, email addresses and the draft title),
|
|
but also references (including RFCs, by instance) are made available through
|
|
a special syntax at the beginning of the Markdown file.
|
|
|
|
Makefile contains the build instructions to generate the I-Ds in the required
|
|
ASCII and xml2rfc v2 forms accepted by the IETF submission system. Additionally,
|
|
it also creates an HTML version.
|
|
|
|
By default, revision number (REV) is set to "00": make sure to increment this
|
|
as IETF contributions are furthered.
|
|
|
|
|
|
Version Control System (Mercurial)
|
|
==================================
|
|
|
|
Most important commands:
|
|
|
|
* download repository / initialization
|
|
1) hg clone https://pep.foundation/dev/repos/internet-drafts/
|
|
|
|
|
|
* Update local directories to latest repository state:
|
|
1) hg pull
|
|
2) hg update
|
|
|
|
Note: Merge handling may be required to take care of
|
|
(if indicated after hg update)
|
|
|
|
|
|
* Upload local changes to repository
|
|
|
|
Important: To avoid conflicts, _always_ update the local directories
|
|
to latest repository state (see commands in last bullet point)
|
|
_before_commit_!
|
|
|
|
1) hg commit -m "<Changelog, short description of changes>" [ <filename> ]
|
|
2) hg push
|
|
|
|
|
|
More information:
|
|
|
|
* https://www.mercurial-scm.org/
|
|
* https://www.mercurial-scm.org/wiki/Tutorial
|