Here’s a draft diagram of the specification publication process:
Working groups publish specifications as follows:
- Working groups use source code repositories to hold their specification sources. These repositories are currently either under bitbucket.org/openid/ or github.com/openid/.
- Specification sources are typically either XML, which is compiled with xml2rfc, or Markdown, which is complied with a variety of different toolchains.
- HTML and optionally .txt versions of the specifications are complied from the source.
- The filenames of the source and outputs should be the same except for the extensions. For instance example-1_0.md should compile to example-1_0.html and possibly also to example-1_0.xml and example-1_0.txt.
- Working groups should periodically publish a stable specification draft to
openid.net/specs/
whenever a significant set of self-consistent edits have been made. For actively maintained specifications, this should occur at least once every few months. - Stable specification drafts are sequentially numbered, starting with -00 for the initial working group draft. The draft number is incremented every time a stable draft is published to
openid.net/specs/
. Draft numbers are never reused and numbered drafts published toopenid.net/specs/
are never overwritten. - When a spec draft is published to
openid.net/specs/
, this should be announced on the working group mailing list. The announcement should include the history entries for the draft, which describe the changes made.
To publish a draft to openid.net/specs/
, specification editors and/or working group chairs perform these steps:
- Verify that the specification contents conform to the requirements at Naming and Contents of Specifications.
- Compile the spec from the most recent source in the working group repository.
- Always create an HTML version.
- Creation of a .txt version is optional.
- If the specification source is Markdown and the spec compilation toolchain uses XML as part of the process, also retain the XML version.
- If the specification uses multiple source files, create a .zip file containing all the sources from which the specification was compiled.
- Copy the source and output files to filenames adding the draft number. So for example, if your source filename is example-1_0.md and your output files are example-1_0.xml and example-1_0.html and your new draft number is 07, also copy these files to the filenames example-1_0-07.{md,xml,html}. If you had multiple source files, also copy example-1_0.zip to example-1_0-07.zip.
- Publish both the files without draft numbers and the files with draft numbers to
openid.net/specs/
. Currently to do this, you:- Use a SCP client such as WinSCP and log into web3.osuosl.org.
- Change directory to
/var/www/openid.net/htdocs/specs/
. - Copy the files without and with draft numbers from your local disk to this directory. (The ones without draft numbers will overwrite the then-previous current drafts.)
- Your files will then be available at
openid.net/specs/
. - Note that this manual SCP step is planned to be replaced by tooling. Currently Torsten Lodderstedt, Mark Haine, Mike Leszcz, Marie Jordon, and Mike Jones have accounts at web3.osuosl.org. In the short term, you will need to ask one of them to do this step for you.
Some working groups also publish Editor’s Drafts that correspond to the latest sources in the working group repository. These are published as follows:
- Build an HTML version following each push to the source repository. Some working group use tooling to automate this process.
- Update the HTML version in the working group’s page in Editor’s Draft repository, which is currently either under
openid.bitbucket.io
oropenid.github.io
. For example, FAPI Editor’s Drafts are published at https://openid.bitbucket.io/fapi/. - Building and publishing Editor’s Drafts can be automated. For example, the some of the OpenID4VC Editor’s Drafts are automatically built and published at https://openid.bitbucket.io/connect/ when pushes occur to https://bitbucket.org/openid/connect/.
Documenting the compilation toolchain used:
-
A gap we haven’t addressed to date is documenting the tool chain used to compile each spec, so that the process is reproducible. When everything used xml2rfc v1, everything was reproducible. But now there are multiple versions of xml2rfc and multiple Markdown tool chains, some of which involve invoking custom Docker containers. We’re not in a good place in that regard at present, since compiling specs currently requires knowledge that is mostly only known by the individual spec editors. It would be good to at least describe the build process used in the repository’s
readme.txt
file so that others (such as the OpenID Foundation Secretary) will be able to build the specs.