DocStd.tex

\documentclass[11pt,a4paper]{ivoa}
\input tthdefs
\input gitmeta

\usepackage{todonotes}

\title{IVOA Document Standards}

\ivoagroup{Standards and Processes}

\author{Genova, F.}
\author{Arviset, C.}
\author{Demleitner, M.}
\author{Glendenning, B.}
\author{Molinaro, M.}
\author{Hanisch, R.J.}
\author{Rino, B.}

\editor{Demleitner, M.; Dowler, P.}

\previousversion[http://ivoa.net/documents/DocStd/20170517/]{REC-2.0}
\previousversion[http://ivoa.net/documents/DocStd/20100413/]{REC-1.2}
\previousversion[http://ivoa.net/documents/DocStd/20031024/]{REC-1.0}


\begin{document}
\begin{abstract}
The International Virtual Observatory Association (IVOA) issues various
documents in foster interoperability of astronomical data and services.
This document describes the types and roles of these documents and
their review processes.
\end{abstract}


\section*{Acknowledgments}

This document is based on the W3C documentation standards, but has been
adapted for the IVOA.

\section*{Conformance-related definitions}

The words ``MUST'', ``SHALL'', ``SHOULD'', ``MAY'', ``RECOMMENDED'', and
``OPTIONAL'' (in upper or lower case) used in this document are to be
interpreted as described in IETF standard RFC2119 \citep{std:RFC2119}.

The \emph{Virtual Observatory (VO)} is a
general term for a collection of federated resources that can be used
to conduct astronomical research, education, and outreach.
The \href{https://www.ivoa.net}{International
Virtual Observatory Alliance (IVOA)} is a global
collaboration of separately funded projects to develop standards and
infrastructure that enable VO applications.


\section{Document types}
\label{sect:doctypes}

The IVOA publishes three types of documents:

\begin{bigdescription}
\item[Recommendation track documents]  These are specifications, guidelines,
etc.  produced by Working Groups. Documents on the Recommendation track
may progress from Working Draft (WD) to Proposed Recommendation (PR) and
finally to Recommendation (REC).

\item[Endorsed Notes track documents] An IVOA Endorsed Note is a document
produced within the IVOA which is subject to a review process, but not
as heavyweight as the recommendation track process (e.g., implementation
notes, etc.). Documents on the Endorsed Note track may progress from
Notes, with eventually a Proposed Endorsed Note phase (PEN), to Endorsed
Notes (EN). Endorsed Notes may refer to a REC.

\item[IVOA Notes]  An IVOA Note is a dated, public record of an idea, comment,
or document.  Authorship of a Note may vary greatly (e.g., by an IVOA
Working Group, by an IVOA member, etc.).
\end{bigdescription}

All public documents are available at the IVOA document repository Web
site, \url{http://www.ivoa.net/documents/}.  The IVOA will make every effort to
make archival documents indefinitely available at their original address
in their original form.

The IVOA Executive Committee appoints a Documentation Coordinator (DC)
who oversees the Document Repository and assures that documents conform
to these guidelines.

The DC may reformat, rename, or renumber documents so as to conform to
changes in IVOA practice (e.g., changes to document styles or the
“Status of this Document” section).

Each public document must clearly indicate whether it is a Note, Working
Draft (WD), Proposed Recommendation (PR), Recommendation (REC), Proposed
Endorsed Note (PEN), or Endorsed Note (EN).

The primary language for IVOA documents is English.

\subsection{Status}

Each document must include a section about the status of the document,
intended to set the expectations as to the maturity and stability of
its content, in particular for persons unfamiliar with IVOA practices.
Standard wording for status declarations of the various IVOA document
types are found in appendix~\ref{app:statustexts}.

Documents are free to change or amend these texts as necessary, but this
should be limited to exceptional circumstances.

\subsection{Naming and version numbering conventions}

IVOA document names have five components:

\begin{enumerate}
\item A document type code:  NOTE, WD (Working Draft), PR (Proposed
Recommendation), REC (Recommendation), PEN (Proposed Endorsed Note) or EN
(Endorsed Note).

\item A concise name, which should be a reasonable condensation of the
document title.

\item A version number of the form I.J, where I and J are integers 0, 1,
2, \dots 9, 10, 11, \dots

\item A date.  The date is the GMT date on which the current version of
the document was produced, in the format YYYYMMDD.  (This does not allow
for multiple revisions of a document to be released within one 24-hour
period.)

\item An extension (.html, .pdf, .doc, etc.) indicating the media type.
\end{enumerate}

The first four components are concatenated, separated by hyphens.

Version numbers follow these guidelines:

\begin{itemize}
\item The number to the left of the (first) decimal point starts with 0 for
documents that are being discussed within a Working Group prior to
publication for IVOA-wide review.  The number increments to 1 for the
first public version, and to 2, 3, \dots, for subsequent versions that are
not backward compatible and/or require substantial revisions to
implementations.

\item The number to the right of the decimal point is an integer counter,
beginning with 0 and increasing in simple cardinal order (0, 1, 2, \dots
9, 10, 11, \dots).  This number does not track every revision to a
document, but rather, denotes a logical version or conceptually
consistent view.  This number should only be incremented when there are
significant and substantial changes to text but few (minor) or no
changes required of implementations. The version number normally remains
fixed as a document is promoted from Working Draft to Proposed
Recommendation to Recommendation, with editorial revisions indicated by
the change of date.

\item After a document reaches Recommendation or Endorsed Note status,
subsequent revisions retrace the promotion process.  Changes that are
backward compatible result in increments in the number to the right of
the decimal place (1.1, 1.2, \dots).  Changes that are not backward
compatible require an increment of the number of the left of the decimal
place (2.0), with subsequent backward compatible revisions following the
same pattern (2.1, 2.2, \dots).
\end{itemize}

The final published and approved Recommendation retains the date on the
title page of the document, but the date is removed from the document
filename in order to simplify reference to the document.

The following examples show a typical name and numbering progression for
a sample document.

\begin{tabular}{lp{0.6\textwidth}}
NOTE-MyNewIdea-1.0-20081001.pdf & (initial idea)\cr
WD-ConciseName-0.1-20081225.pdf & (first Working Draft, in WG)\cr
WD-ConciseName-0.1-20081231.pdf & (revised 6 days later)\cr
WD-ConciseName-0.2-20090115.pdf & (text revised substantially)\cr
WD-ConciseName-0.2-20090201.pdf & (final version in WG before PR)\cr
WD-ConciseName-1.0-20090301.pdf & (published first version)\cr
PR-ConciseName-1.0-20090501.pdf & (promoted to PR)\cr
PR-ConciseName-1.0-20090615.pdf & (updated after RFC)\cr
PR-ConciseName-1.0-20090801.pdf & (updated after TCG review)\cr
REC-ConciseName-1.0.pdf       &   (accepted as REC; date, e.g., 20090901
appears on title page)\cr
WD-ConciseName-1.1-20100628.pdf & (first update to WD in WG; does not
affect implementation)\cr
WD-ConciseName-1.1-20100715.pdf & (revised text)\cr
WD-ConciseName-1.1-20100801.pdf & (revised text)\cr
PR-ConciseName-1.1-20100815.pdf & (promoted to PR)\cr
PR-ConciseName-1.1-20100915.pdf & (updated after RFC/TCG review)\cr
PR-ConciseName-1.1-20101001.pdf & (updated after RFC/TCG review)\cr
REC-ConciseName-1.1.pdf       &   (accepted as REC)\cr
WD-ConciseName-2.0-20110628.pdf & (major update to WD in WG; does affect
implementation)\cr\cr
WD-ConciseName-2.0-20110715.pdf & (revised text)\cr
WD-ConciseName-2.0-20110801.pdf & (revised text)\cr
PR-ConciseName-2.0-20110815.pdf & (promoted to PR)\cr
PR-ConciseName-2.0-20110915.pdf & (updated after RFC/TCG review)\cr
PR-ConciseName-2.0-20111001.pdf & (updated after RFC/TCG review)\cr
REC-ConciseName-2.0.pdf       &   (accepted as REC)\cr
\end{tabular}

In the case of an EN making reference to an existing recommendation, it
is recommended that the Concise Name of Endorsed Notes includes a
reference to the Concise Name used in the relevant REC, and an
indication of its relationship to the REC (e.g.,
ConciseName-Implementation).

Names will be reviewed and may be modified by the Document Coordinator
to be consistent with these conventions.  All versions 1.0 and higher
are stored in the IVOA Document Repository.

\subsection{Format}

IVOA documents must be available in both PDF and HTML formats and must
be developed in publicly accessible version control systems.

The use of the IVOA's designated authoring system is strongly encouraged
to foster cooperation and enable painless resumption of standards
development by other editors as well as the management of errata.

See \citet{note:ivoatexdoc25} for a non-normative overview of IVOA
practices as of the current revision of this document.

\subsection{How to publish a document}

Documents are entered into the IVOA Document Repository by the Document
Coordinator in response to a request from a Working Group chair or the
person primarily responsible for editing a particular document.  The
technical details of the submission process are determined by the
document coordinator together with the TCG. Current information is
available on a web page linked from the IVOA document repository.
Absolute path names must be avoided when packaging the document(s) as
well as when creating internal links within the document.

When problems are encountered during the submission process (e.g.,
unavailability of the site or too large files), it is necessary to agree
with the DC on different means of electronic transfer.

\subsection{Supplementary resources}

The Document Coordinator maintains a repository of supplementary
resources, such as XML schemas or RDF vocabulary definitions.
Implementations should use
these in preference to copies stored elsewhere.  There is, however, no
requirement to use them if a different implementation yields compliance
with a given standard.

At the same time, authors of auxiliary
files should include comments stating which standards and versions
thereof they reflect.


\section{Standards process}
\label{sect:proc}

The IVOA standards process is used to build consensus around a Virtual
Observatory technology, both within IVOA and in the VO community as a
whole. IVOA Working Drafts become Recommendations by following this
process. The labels that describe increasing levels of maturity and
consensus in the standards process are:


\begin{bigdescription}
\item[Note]  An IVOA Note is a dated, public record of an idea, comment,
practice, experience, insight, advice, guideline, or policy. Authorship
of a Note may vary greatly (e.g., by an IVOA Working Group, by an IVOA
member, etc.).  In some circumstances a Note may be the basis for a
Working Draft or Proposed Endorsed Note/Endorsed Note, but typically
Notes are used to describe items relevant to the IVOA other than
descriptions of standards or protocols.

\item[Working Draft]  A document begins on the recommendation track as a
Working Draft. A Working Draft is a chartered work item of a Working
Group and generally represents work in progress and a commitment by IVOA
to pursue work in a particular area.  The label ``Working Draft'' does not
imply that there is consensus within IVOA about the document.

\item[Proposed Recommendation]  A Proposed Recommendation is believed to meet
the relevant requirements of the Working Group's charter and any
accompanying requirements documents, to represent sufficient
implementation experience, and to adequately address dependencies from
the IVOA technical community and comments from previous reviewers.

\item[IVOA Recommendation]  An IVOA Recommendation is a document that is the
end result of extensive consensus-building within the IVOA about a
particular technology or policy.  IVOA considers that the ideas or
technology specified by a Recommendation are appropriate for widespread
deployment and promote IVOA's mission.
\end{bigdescription}

Generally, Working Groups create Working Drafts with the intent of
advancing them through the standards process. However, publication of a
document at one maturity level does not guarantee that it will advance
to the next. Some documents may be dropped as active work or may be
subsumed by other documents.  If, at any maturity level of the standards
process, work on a document ceases (e.g., because a Working Group or
activity closes, or because the work is subsumed by another document), a
final version of the document should be issued and stored in the
“Historical” category, with the status section noting that work on this
document has concluded, and for what rationale, and with links provided
to relevant follow-on documents. Any time a document advances to a
higher maturity level, the announcement of the transition must indicate
any formal objections.  If, at any maturity level prior to
Recommendation, review comments or implementation experience result in
substantive changes to a document, the document should be returned to
Working Draft for further work.  The relationship between Working
Drafts, Proposed Recommendations, and Recommendations is shown in the
figure below.

Some documents which are not IVOA standards (e.g., the IVOA Architecture
Document, implementation notes, etc.) may require discussion, evaluation
and endorsement. They are subject to a lighter-weight endorsement
process, the Endorsed Note one, which is described in
Section~\ref{sect:en}.

\subsection{Working Draft (WD)}

Official IVOA documents begin as Working Drafts.  Before a document
becomes a Working Draft, it is within the
purview of a Working Group; this stage is sometimes called an Internal
Working Draft.  Internal Working Drafts may undergo numerous
revisions during their development.  During this volatile phase, documents
are not shown in the IVOA document repository, but
rather are maintained by the responsible working group a suitable
version control system.  The IVOA history of a document starts with its
promotion to a Working Draft.

\paragraph{Entrance criteria}  A Working Draft is published at the discretion of a
Working Group once the WG is satisfied that the document is sufficiently
developed to merit broader exposure and feedback.  Publication of a
Working Draft is not an assertion of consensus, of endorsement, or of
technical and editorial quality. Consensus is not a prerequisite for
approval to publish; the Working Group may request publication of a
Working Draft even if it is unstable and does not meet all Working Group
requirements.  Working Drafts are subject to review by the document
coordinator for compliance to these guidelines.

\paragraph{Ongoing work}  Once a Working Draft has been published, the Working
Group should continue to develop it by encouraging review and feedback
within and outside of IVOA.  The TCG may decide to classify a Working
Drafts which is no longer under development in the “Historical”
category.

\paragraph{Next maturity level}  After a suitable review and trial period, the
chair of the Working Group may promote the Working Draft to a Proposed
Recommendation.  Such advancement should occur only when the chair of
the Working Group is satisfied that consensus has been reached, and more
formal and extensive review is now warranted.  Advancement to Proposed
Recommendation implies:

\begin{enumerate}
\item The Working Group has fulfilled the relevant requirements of the
Working Group charter and those of any accompanying requirements
documents.

\item The Working Group has formally addressed issues raised during the
development and review process (possibly modifying the document).

\item The Working Group has reported all formal objections.

\item When applicable, the Working Group should be able to demonstrate two
interoperable implementations of each feature, and validation tools
should be available. The rules for implementation references can be
specific to a working group. If the chair of the Working Group believes
that broader review is critical, the chair may advance the document to
Proposed Recommendation even without adequate implementation experience
or validation tool availability.  In this case, the document status
section should indicate why the chair promoted the document directly to
Proposed Recommendation.  A report describing the implementations or any
associated validation tools should be published as a Note, or should be
documented as part of the Request for Comments (see below).
\end{enumerate}

\subsection{Proposed Recommendation (PR)}
\label{sect:rfc}

\paragraph{Entrance criteria}  Proposed Recommendations are published by the chair
of a Working Group following the criteria described above.  Proposed
Recommendations are considered to be technically mature and ready for
wide review.

\paragraph{Ongoing work}   The Working Group should continue to encourage review
and feedback within and outside of IVOA. The TCG may decide to classify
the Proposed Recommendations which are no longer under development in
the “Historical” category.

\paragraph{Next maturity level}  The chair of the Working Group that developed the
Proposed Recommendation may call for a formal Request for Comments
(RFC).  The RFC is sent to the widest possible IVOA distribution lists
(interop@ivoa.net) and published by adding a link to the RFC on the IVOA
document repository web page.  Distribution of the RFC initiates a
six-week public review period.  All comments submitted during this
review period must be posted publicly and responded to publicly.  The
chair and vice-chair of the other Working Groups must examine the
Proposed Recommendation during the RFC period and post comments in the
public record.  The chair and vice-chair of the Interest Groups are also
encouraged to examine the Proposed Recommendation and to post comments
in the public record. Comments from TCG members (the WG and IG chairs
and vice-chairs) may be no more than “read and approved“ or “no
dependency” but if TCG members have significant concerns it is during
the RFC period that these must be documented.  It is sufficient to have
one input per WG and IG but it is expected that the Chairs of a Group
work in co-operation with each other.

Following the RFC period, the editor(s) may issue additional document
versions that take into account the comments received in order to reach
consensus, or the WG Chair may decide to return the document to Working
Draft if the maturity level appears not to be sufficient. The Chair
indicates the availability of the new version on the RFC page and
publishes the information to the same wide distribution list, with a
link to the RFC and the information that comments on this new version
should be posted within two weeks. In particular, parties who made
comments during the RFC are invited to indicate whether they see their
comments suitably addressed; the WG chair may issue additional document
versions in order to reach a consensus. The TCG then has two weeks to
make a final review of the document and to issue a final binary approval
(yes/no) noted on the RFC public comment website (“TCG vote”). WG chairs
must express a vote, IG chairs are invited to participate in the review
and express a vote.

PRs being brought forward for promotion to REC should, when applicable,
have at least two interoperable implementations and validation tools
should be available.  In its final review the TCG may agree to waive
these requirements if there are extenuating circumstances.  If the TCG
does not agree to waive the requirement regarding interoperable
implementations and/or availability of validation tools, but there are
otherwise no outstanding issues or unresolved problems, the final
decision on promotion of the PR to REC rests with the Executive
Committee.  The chair of the TCG, working in consultation with the chair
of the Working Group responsible for the PR, then makes a final summary
recommendation, including information about the availability of
reference implementations and validation tools, and the chair of the TCG
forwards this recommendation to the Executive Committee for review and
approval. If the Executive Committee is satisfied that the procedure has
been properly followed, they promote the document to a Recommendation.

\subsection{Recommendation (REC)}

\paragraph{Entrance criteria}  Recommendations are published by the IVOA Executive
Committee following the criteria described above.  Recommendations are
the final form of IVOA documents and constitute an IVOA Standard.

\paragraph{Ongoing work}   The WG chair in cooperation with the document editors
should prepare a StandardsRegExt record for the new REC and submit it to
the Registry of Ressources.  Recommendations may need to be revised and
extended as time goes on.  Significant revisions of Recommendations must
proceed through the Working Draft and Proposed Recommendation phases.  A
significant revision is any revision that requires changes in software
based on the document. Errata can be attached to a Recommendation
following the procedure described in section 4. Further work on the
evolution of the recommendation is documented in the relevant Working
Group pages.

\paragraph{Next maturity level}  A Recommendation is the highest level of maturity
for an IVOA document.  The IVOA Executive Committee may propose that
Recommendations be endorsed as standards by the International
Astronomical Union, working through IAU Commission B2 Data and
Documentation or its successor. The TCG may decide to deprecate a
Recommendation, which is then kept in the Document repository in the
“Historical” category.

\begin{figure}
\includegraphics{procsummary.png}
\caption{The IVOA REC process in a graphical representation}
\label{fig:procsummary}
\end{figure}

\subsection{Document promotion process summary}

The IVOA document promotion process is summarized in graphical form in
Figure~\ref{fig:procsummary}.

\begin{enumerate}
\item Working Group prepares Working Draft (version $\geq 1.0$) and submits to
Document Coordinator for posting in the IVOA Document Repository.

\item Working Group reviews the Working Draft. Two reference
implementations of any associated software are expected, as well as
provision of validation tools, otherwise an explanation should be
provided.

\item The Chair of the Working Group, with consent of the WG, promotes the
document to a Proposed Recommendation and submits it to the Document
Coordinator for posting in the IVOA Document Repository.

\item The Chair of the Working Group issues a formal Request for Comments
(RFC) to the e-mail distribution list interop@ivoa.net. The RFC and all
comments must be logged on a globally editable page whose URL is given
in the RFC. A minimum comment period of 6 weeks must be allowed. The
chairs and vice chairs of other Working Groups are required to examine
Proposed Recommendations during the RFC period and to post comments in
the public record, the chairs and vice-chairs of Interest Groups are
invited to do so.

\item The Working Group Chair and/or editor(s) respond to comments on the
RFC page. If comments lead to significant changes to the document, the
WG Chair may decide to revert the document status to Working Draft (back
to Step 1).

\item If comments are addressed to the satisfaction of the WG Chair and WG
members, the WG Chair requests a final vote, to be completed within 2
weeks, by the Technical Coordination Group, and they add their final
yes/no vote to the RFC record.  Working Groups are required to provide a
vote, Interest Groups are encouraged to do so. The chair of the
Technical Coordination Group, working in consultation with the chair of
the Working Group responsible for the PR, then makes a final summary
recommendation and the chair of the Technical Coordination Group submits
the PR to the Executive Committee for approval.

\item The Executive Committee is polled by the IVOA Chair to ascertain if
there is consensus for promotion to Recommendation.

\item If yes, the IVOA Chair reports on approval to the TCG and WG Chairs
and asks the Document Coordinator to update the document status to
Recommendation. If no, the concerns of the IVOA Executive need to be
resolved and a new poll taken, or if serious revisions are required, the
document would revert to Step 1.

\item The IVOA Executive may propose to the IAU Commission B2 or its
successor that IVOA Recommendations be endorsed as IAU Standards.
\end{enumerate}

\begin{figure}
\includegraphics{ensummary.png}
\caption{The IVOA Endorsed Note process in a graphical representation}
\label{fig:ensummary}
\end{figure}


\section{Endorsed Notes process}
\label{sect:en}

Certain documents need a certain level of normative power but do not
quite fit the REC path outlined before, either because they span several
or all Working Groups, because they are something like annexes to other
standards, or because they describe policies and practices rather than
protocols.

For such documents, die IVOA follows the Endorsed Note (EN) process,
managed by the Technical Coordination Group exclusively.  Some
prototypical examples for ENs existing at the time of writing are:

\begin{itemize}
\item  	XML Schema Versioning Policies \citep{2018ivoa.spec.0529H} --
this is a policy affecting almost all WGs.

\item 	IVOA Architecture \citep{2024ivoa.spec.1114E} -- this is a
document to which all WGs contribute in the same way and that
needs to reflect a consensus within the IVOA.

\item Discovering Data Collections Within Services
\citep{2019ivoa.spec.0520D} -- this is a policy, laying out a practice
of how Registry standards are applied, to be agreed upon between
Registry and Apps.

\item Adopting the UAT as an IVOA vocabulary \citep{2022ivoa.spec.0722D}
-- this is effectively an external annex to Vocabularies in the VO.
\end{itemize}

\paragraph{Entrance  criteria}  Endorsed  Notes  can  be  proposed  by  an
Interest  Group,  a  Working Group,  the  Technical  Coordination
Group,  or  more  generally  be  documents  produced within the IVOA.
They circulate among the authors, and in the Working Group, Interest
Group,  or  the  Technical  Coordination  Group  until  they  reach  a
sufficient  maturity  level.  This draft can be published as a normal
Note beforehand, but this is not required.

\paragraph{Proposed  Endorsed  Note  (optional)}  A  Proposed  Endorsed  Note  is
submitted  to  a Request for Comment following the procedure described
in Section~\ref{sect:rfc}.

\paragraph{Endorsed Notes} An Endorsed Note has been endorsed by the Technical
Coordination Group.  Endorsed  Notes  constitute  valuable  information
for  the  IVOA  community,  by themselves or as complement of
Recommendations.

\paragraph{Process} The Endorsed Note process is managed by the Technical
Coordination Group.  The party proposing the Note endorsement submits it
to the TCG. The TCG decides the process to apply in the specific case of
the document. There are two possibilities:

\begin{enumerate}
\item The  TCG  decides  a  Request  for  Comments  is necessary,
usually to ensure maximum community participation.  The document is then
published on the IVOA document repository as a PEN.  This PEN is then
reviewed like a PR is (see Sect.~\ref{sect:rfc}.

\item The  TCG  decides  that  sufficient community participation has
taken place for the specific content of the note and that there  is  no
need  for an RFC period.  It can then promote the document directly to
Endorsed Note.
\end{enumerate}

For  each  meeting  of  the  Executive  Committee,  the  TCG  chair
prepares  a  list  of  the Endorsed  Notes  passed  since  the  last
meeting  of  the  Executive  Committee  with  a summary of their
history. The Executive Committee can withdraw an Endorsed Note with an
explanation of the withdrawal reason.

Proposed  Endorsed  Notes  and  Endorsed  Notes  appear  in  the  IVOA
Document Repository.  Endorsed  Notes  linked  to  a  standard  are
visible  in  the  relevant  standard landing page.\todo{We don't do
this.  Do it or drop this language?}


\section{Errata}
\label{sect:errata}

As a Recommendation or Endorsed Note is published
in the IVOA document repository, a
globally editable\footnote{As of this writing, the page will reside in
IVOA's wiki, but the technical details are not part of this standard.}
titled
$\langle$ConciseName$\rangle$-$\langle$CurrentVersion$\rangle$-Errata is
created, and a link to it is page created in the working group's landing
page, as well as in the header of the Standard document text.  This
“-Errata“ page will have three sections:

\begin{itemize}
\item Accepted Errata
\item Rejected Errata
\item Proposed Errata
\end{itemize}

One such Errata-page is maintained per Recommendation or Endorsed Note
(i.e., standards
version); as a new version of the REC is passed, a new, empty -Errata
page is created and linked to the working group’s landing page and in
the header of the Standard document text.  All the Errata sections will
consist of listings whose items are pointers to globally editable pages
titled
$\langle$ConciseName$\rangle$-$\langle$CurrentVersion$\rangle$-Erratum-$\langle$RunningNumber$\rangle$
where the
text for the erratum will physically reside.  The Errata page must be
linked from the document text and from the standard's landing page, even
when it is still empty.  Rejected and Proposed Errata not yet reviewed
will continue living in the -Errata page to document present and past
activity on the specification.  The Errata page is under the
responsibility of the relevant WG chair, who acts in collaboration with
the parties proposing a new Erratum. Sections on Accepted and Rejected
Errata may only be edited by the responsible working group chairs on
behalf of the TCG as discussed below.  Edits made by other parties must
be removed by the Working Group chair.

Errata have a formal process.  To start it, any interested party can
create a proposal for an erratum which should contain text, when
relevant, on each of

\begin{itemize}
\item  Original wording and new wording
\item  Rationale
\item Impact Assessment
\end{itemize}

If elements are to be deleted or added from the document, the
surrounding text should be identified.

The proposed erratum is then announced on the Working Group's mailing
list, which should also be the main medium of discussing the erratum.
Comments can also be added on the erratum page. Errata likely to affect
other working groups should also be announced to the full VO community.
Before each meeting of the TCG, the TCG chair collects a list of
proposed errata from the WG chairs.  It must be circulated to all TCG
members at least two weeks before the meeting.  The texts of the errata
under consideration are, at that point, frozen until the TCG meeting.
At each TCG meeting, a vote is taken on each erratum circulated in this
way.  All WGs (represented by a consensus of chair and vice-chair if
both are present) must vote one of accept, defer, or reject. A working
group vote can be casted by email when none of the chairs can attend the
TCG meeting.  An erratum is accepted or rejected if there is general
consensus; in all other cases which might require further discussion it
remains a proposed erratum.  The TCG may amend an Erratum with editorial
changes proposed in-session. The vote on an erratum can be done by email
if needed.  Errata either accepted or rejected are permanently frozen,
i.e., no further edits are allowed on the pages that describe them. In a
last edit, the WG chair or document coordinator record the acceptance
date (and hence the freezing date) of the erratum.  Links to accepted
(rejected) errata on the -Errata pages are moved by the WG chair to the
Accepted (Rejected) Errata section.   Errata deferred are unfrozen and
open to further discussion and/or refinement.

For each meeting of the Executive Committee, the TCG chair prepares a
list of the errata passed since the last meeting of the Executive
Committee with a summary of their history. The Executive Committee can
withdraw an erratum with an explanation of the withdrawal reason. Such
errata will be marked as rejected in the document repository, possibly
with a reference to a superseding erratum.

A list of all errata accepted for a document together with links to them
is also maintained on the document's landing page in the IVOA document
repository while the version in question is the most recent one.

\section{The Document Repository}
\label{sect:doccoll}

The IVOA Document Repository is the primary source for IVOA documents.
IVOA users, especially from outside the core collaboration, should
always be directed to the Document Repository rather than be sent
private copies of documents.

The IVOA Document Repository is organized so as to lead readers most
naturally to the current versions of all documents in all document
classes.  A document archive is also maintained so that previous
published versions of documents remain available.

\appendix
\section{Changes from Previous Versions}

\subsection{From 2.0 to 2.1}

\begin{itemize}
\item Now formally requiring both HTML and PDF; also, dropping the
reference to outdated templates and nudging people towards ivoatex.

\item Explicitly sanctioning the existing practice of submitting
unpublished notes to the TCG for endorsement.
\end{itemize}


\subsection{From 1.2 to 2.0}

\begin{itemize}
\item  Updated table of content
\item  Address of the document repository changed to
http://www.ivoa.net/documents/
\item In Section 1, added reference to the Proposed Endorsed Notes and
Endorsed Notes type of document.
\item In Section 1.2, added reference to the Annex with recommended document
status texts
\item In Section 1.2, added reference to PEN and EN
\item In Section 1.2, corrected typos in the examples of names, updated
description of the progression to take into account the changes in the
processes (does not affect implementation, RFC/TCG review)
\item In section 1.3, added reference to the usage of volute
\item In Section 1.4, deleted reference to the way the submission process is
implemented
\item In section 1.5, added a reference to the XML Schema Versioning Policy
Endorsed
Note and to errata.
\item In Section 2, added reference to Draft Endorsed Note as a possible
evolution of a Note
\item In Section 2, added ‘on the recommendation track’ to the WD description
\item In Section 2, updated the link to the IVOA mission in the footnote
\item In Section 2, added a reference to the “Historical” category
\item In Section 2, at the end of the introduction, added a final paragraph to
introduce the Endorsed Notes process.
\item In Section 2.1, added a reference to the “Historical” category
\item In Section 2.1, deleted the sentence “Each feature of the Working Draft
has been implemented, added “When applicable” in the discussion of
reference implementations and validation tools, added the fact that
rules for implementation references can depend on the WG matter, add the
possibility to waive the requirement to have a validation tool
\item In Section 2.2, added a reference to the “Historical” category
\item In section 2.2, Next maturity level, first paragraph, deleted the
initial two-week publication period and the reference to the possibility
to return the document to WD
\item In section 2.2., added the possibility to issue incremental versions or
to return to WD
\item In Section 2.2, Next maturity version, second paragraph, TCG members to
comment PRs during the RFC, TCG Review limited to yes/no vote (“TCG
vote”); RFC 6 weeks instead of 4, iterative process for RFC, TCG review
2 weeks instead of 4; update of the figure
\item In Section 2.2, re-ordering of the text to put together the discussion
of reference implementations, adding a reference to validation tools and
how to proceed when the two required reference implementations and/or
the validation tools are not available when promotion to REC is
submitted
\item In Section 2.2, clarified that the Chair and Vice-Chair of a Group must
examine a PR and that one vote per Group is sufficient but it is
expected that the Chairs of a Group work in co-operation with each other
\item In section 2.2, changed the Executive Committee role to “be satisfied
that the procedure has been properly followed”
\item In Section 2.3, added the requirement to provide a StandardRegExt record
\item In Section 2.3, addition of a reference to errata and other on-going work
\item In Section 2.3, replacement of IAU Commission 5 by IAU Commission B2
\item In Section 2.3, added a reference to the “Historical” category
\item In Section 2.4, 2., added a reference to explanations to be provided to
waive the reference implementation and validation software requirement
\item In Section 2.4, 4., changed “TWiki” to “globally editable page”
\item In Section 2.4, 4. deleted the reference to the initial two-week period
\item In Section 2.4, 5. Clarify the respective roles of the WG chair and editor(s)
\item In Section 2.4, update of the summary figure to reflect the new Recommendation
process
\item  Addition of Section 3 to describe the Endorsed Notes Process
\item  Added Section 4 on -Errata pages and Errata
\item In Section 3, Section numbering changed to Section 5
\item In Section 5, added reference to PEN/EN and “Historical” documents
\item In Section 4, Section numbering changed to Section 6
\item Template text added for Proposed Endorsed Notes and Endorsed Notes.
\item In Section 1.3, changed the required format for documents to PDF and
added
\item In Section 1, added explicit reference to the URL for the IVOA document
repository.  In Section 1, added “The DC may reformat, rename, or
renumber documents” to
\end{itemize}

\subsection{From 1.1 to 1.2}

\begin{itemize}
\item Allow for standardization in naming and numbering of IVOA documents.
\item  Changed “technical report” to “document” throughout.
\item  Rewrote Section 1.2 to include new naming and numbering scheme using
.pdf file extensions to be consistent with change to Section 1.3.
\item requirement to submit and store document in its original format.
\item  Added Section 1.4 “How to Publish a Document” from the IVOA Note,
Guidelines and Procedures for IVOA Document Standards Management V1.0.
\item  Added Section 1.5 “Supplementary Resources” from the IVOA Note,
Guidelines and Procedures for IVOA Document Standards Management V1.0.
\item In Section 2, added paragraph to clarify the function of Notes.
\item In Section 2.1, added introductory paragraph describing early phases of
WD development from the IVOA Note, Guidelines and Procedures for IVOA
Document Standards Management V1.0, and clarified entrance criteria for
Working Draft.
\item In Sections 2.2 and 2.4, updated the role of the TCG in the review of
documents during the RFC period.  Section 2.2 includes text concerning
the requirement for at least two interoperable implementations and under
what circumstances this requirement can be waived.

\item  Added Section 3 “The document collection” with text from Sections 6
and 7 of the IVOA Note, Guidelines and Procedures for IVOA Document
Standards Management V1.0.
\item  Updated table of contents.

\item In Section 2.4, updated the diagram to show more clearly the TCG participation.

\item In Section 2.2, clarified how RFCs are published through the IVOA document

\item In Section 2.1, added text describing documentation of interoperable

\subsection{From 1.0 to 1.1}

\item  The role of the Technical Coordination Group (which comprises the
Working Group chairs and deputies and Interest Group chairs and
deputies) has been made explicit in Section 2.2 describing the RFC
process.

\item  A summary of the process has been added in Section 2.4 and the figure
showing the process has been moved into this new section.

\item  The figure has been updated to reflect the TCG review and to show
that Recommendations may be referred to the IAU as appropriate.

\item  Added Appendix with sample text for describing the Status of a document.
\end{itemize}

\section{Recommended Text for Document Status}
\label{app:statustexts}

The following text examples may be used as templates in the Status
portion of the document.

\subsection{Note}
This is an IVOA Note expressing suggestions from and opinions of the
authors. It is intended to share best practices, possible approaches, or
other perspectives on interoperability with the Virtual Observatory. It
should not be referenced or otherwise interpreted as a standard
specification.

\subsection{Working Draft}
This is an IVOA Working Draft for review by IVOA members and other
interested parties.  It is a draft document and may be updated,
replaced, or obsoleted by other documents at any time. It is
inappropriate to use IVOA Working Drafts as reference materials or to
cite them as other than “work in progress”.

\subsection{Proposed Recommendation}

This is an IVOA Proposed Recommendation made available for public
review. It is appropriate to reference this document only as a
recommended standard that is under review and which may be changed
before it is accepted as a full Recommendation.

\subsection{Recommendation}

This document has been produced by the IVOA [working group name] Working
Group.  It has been reviewed by IVOA Members and other interested
parties, and has been endorsed by the IVOA Executive Committee as an
IVOA Recommendation. It is a stable document and may be used as
reference material or cited as a normative reference from another
document. IVOA's role in making the Recommendation is to draw attention
to the specification and to promote its widespread deployment. This
enhances the functionality and interoperability inside the Astronomical
Community.

\subsection{Proposed Endorsed Note}

This is an IVOA Proposed Endorsed Note for review by IVOA members and
other interested parties. It is appropriate to reference this document
only as a Proposed Endorsed Note that is under review and may change
before it is endorsed or may not be endorsed.

\subsection{Endorsed Note}

This document is been produced by […]. It has been endorsed by the IVOA
Technical Coordination Group as a stable, citable document which
constitutes valuable information for the IVOA community and beyond.

\bibliography{ivoatex/ivoabib,ivoatex/docrepo,local}


\end{document}