EPICS Version 4 Process

EPICS V4 Process, Editors' Draft, 19-Sep-2012

Latest version:
epicsv4process.html
This version:
epicsv4process_20120919.html
Previous version:
epicsv4process_20120412.html
Editors:
Greg White, SLAC, PSI
Bob Dalesio, BNL

Abstract

This document describes the administrative processes of the EPICS V4 Working Group.

The EPICS V4 Working Group is a collaboration of software engineers and physicists involved in the design and implementation of the next major version of EPICS.

For more information about EPICS, please refer to the home page of the Experimental Physics and Industrial Control System.

Status of this Document

This is the 19 Sep 2012 version of the Process document; a slight revision the first draft. However, the processes described here have been largely in effect since September 2011 and have formed the basis of the EPICS V4 Working Group collaboration operations. This revision describes the meaning of Normative in the context of EPICS V4 standards.

Comments are welcome, please address them to the chairs of the EPICS V4 at the EPICS V4 mailing list, https://sourceforge.net/mailarchive/forum.php?forum_name=epics-pvdata-devel

The terms MUST, MUST NOT, SHOULD, SHOULD NOT, REQUIRED, and MAY when highlighted (through style sheets, and in uppercase in the source) are used in accordance with RFC 2119 [RFC2119]. The term NOT REQUIRED (not defined in RFC 2119) indicates exemption.

Table of Contents


Introduction

The process is described by a list of practices and required documents, given in approximately the chronological order in which they are used.

Working Group

The collaboration between individuals working on EPICS Version 4, is formalised as Working Group. As such it has definite participants, who are responsible for the deliverables; and observers, who partake in policy and meetings, but are not required to deliver work.

Participants are expected to contribute 20-30% of their time on the activities of the Working Group. Participants MUST get active approval from their home institution, in writing, delivered to the chairs.

Chairs

One or two individuals take the role of chairs of the Working Group. They draft the charter and are responsible for the charter success criteria. Specific activities of the chairs will include assigning roles to group members, meeting agenda, making sure meetings are productive, deciding on the mechanism of action item, issue, and resolution recording (see below), arbitration and the role of final "decider."

Charter

A Charter document is prepared which defines the duration, deliverables, success criteria, scope (including items out of scope), and funding, of the Working Group. The charter is intended to be the basis for agreement of objectives between the collaborating institutions, and between employers and employees about their EPICS Working Group commitment.

Meetings

Telecon meetings should be held every week or close to that schedule.

Face-to-face meetings should be held, for one or two days, on an approximately quarterly schedule, or as activities require.

Minutes of all meeting should be recorded in some detail and be available for reference among the members and other parties to the charter such as managers and EPICS leadership.

Formal activity tracking

Some activities of the working group should be formally and openly tracked, so that the group can itself administer its own activity and decisions effectively, and so that home institutions and the EPICS community in general can monitor activity. In particular the following should be tracked:

Software

The source code products of the Working Group should be made available to the public, with reference to the EPICS License.

All source code should be accompanied by programmers guidance documentation, and should also be accompanied by fully marked up source code reference documentation such as Doxygen (C++) or JavaDoc (java).

Very clear instructions about how to acquire, build, and link software, should be clearly visible in the group's web site. Prerequisites of the software must be clear.

All software should be managed in a Source Code Management system. Releases should be made including unit tests, ideally within a Continuous Integration Management system.

The association of software implementation version with the version or versions of the normative documents on which that software is associated, should be very clear, and made explicit on the web site.

Public Web Site

The working group should maintain a public web site, where software and document products can be found easily.

The maturity and status of each working group product must be clearly indicated on the web site.

The web site must make clear to the public how to contact the working group, how to provide feedback to the group and how to report bugs in software and specifications. SourceForge is a reasonable platform for the web site.

Document and Software Classifications

This section defines basic terms used to identify the provenance of documents and code of the EPICS V4 Working Group. Where appropriate, working group material SHOULD identify itself as one of these:

Normative

Documents that define a specification of a standard or design being proposed by the Working Group for EPICS, should themselves be written according to a standard. We will call such documents "Normative"; see http://en.wikipedia.org/wiki/Normative#Standards_documents. Normative documents of the EPICS V4 working group are documents which contain prescriptions of what process or software that claim to conform to the standard, ought to do.

Normative documents must contain mostly deterministically specified descriptions of designs and processes (though Normative documents may contain non-normative material to help clarify or illustrate, as long it's clearly shown to be so). Normative software should conform to one or more Normative documents that describe its function. In general, Normative work of the group is intended to be developed collaboratively in the open with the EPICS community. Core products of the working group must be Normative.

Normative code will be documented to an agreed standard level and conform to the Coding Standard Guidelines

Normative documents MUST all follow the same template, which specifies inclusion of text that indicates the status and provenance of the document.

Normative specifications or designs for software (or hardware) should be accompanied by a reference implementation.

Informative
Documents and code additionally made available by the group, for illustration, or as minor test code, or incidental, should not be considered normative. Call those simply "informative"
Internal
Documents and code which are neither normative nor informative in the senses above, should be considered simply internal documents of the group. Note that internal documents may appear on the public web site.

Normative Document Development and Publication Process

Normative documents should go through the following iterative collaboration procedure. This is to ensure that the EPICS community has good opportunity to comment and refine the spec, the final product is broadly useful, and weak or unnecessary specs get dropped.

  1. Editors Draft. This status is used while the writers and editors just develop the spec inside the Working Group. Editors Draft status indicates the spec is not ready to be reviewed
  2. First Public Working Draft. The document is ready for initial review.
  3. Successive "Second", "Third" etc Public Working Draft. As the document is refined, it should be republished to Tech-talk etc, as numbered and dated working drafts.
  4. Last Call. When the working group is satisfied that it has a draft which can form the basis for an EPICS standard, it should publish a Last Call draft. The Working Group should publish this to Tech-talk and be prepared to record their responses to all comments (such as in a mailing list).
  5. When the WG is confident that its spec is ready, it should petition Bob Dalesio and Andrew Johnson to publish the spec as a Recommendation
  6. Recommendation. This status indicates the EPICS community and leaders have accepted the specification and associated software, if any, as part of EPICS, and recommend that other activities build on it.

Contact author: Bob Dalesio, BNL
Last modified: Wed Sep 19 14:58:46 CEST 2012