EPICS Version 4 Process

EPICS V4 Process, Working Draft 25-Nov-2013

Latest version:
This version:
Previous version:
Greg White, SLAC, PSI
Bob Dalesio, BNL


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 25 Nov 2013 version of the Process document. This revision includes the new section on Action Item progress tracking - the way that we track project advancement. 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


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.


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."


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.


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.


Things which are tracked

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:

The tracking mechanism is to use SourceForge (SF) tickets. Each kind of item tracked above will be tracked by a SF ticket type.

AI progress tracking

The Charter defines which projects are important for the following year. For organizational clarity we'll group these into activities:
Basic Development, Network and IOC
APIs and Clients
High Performance Data Processing
Platform Support
Documentation and Web Site

Each project will accomplished by defining and completing ACTION ITEMS (AIs). There may be one or many AIs associated with a project.

    Charter <->> Activities <->> Projects <->> ACTION ITEMS

The status of the ACTION ITEMS of each Project will be tracked by an Agile Development like dashboard. See http://epics-pvdata.sourceforge.net/dashboard.html.

Group participant responsibilities for project tracking

Working group participants are expected to:

  1. Create and also work on the AIs of projects as created by the chairs
  2. Keep the SF ticket of each AI up to date
  3. When starting a new project, propose the initial AIs to the group. Inform the chairs and Bob of any new AI you make on yourself
  4. Link your AI to documented use cases (see below)
  5. Help to keep the dashboard up to date, through editing the dashboard file directly.

In the penultimate telecon of each month we'll review the active AIs in the dashboard.

In the last meeting of each month Bob, as the main money man of EPICS V4, will prioritize what AIs should be worked on the following month.

Prioritization References

Work prioritization should stem from scientific and controls Use Cases as much as possible. Therefore, we will create a new document called Use Cases and APIs. This document will list the ways one might want to get data, and the physics or controls use case in which it would be used. Each AI's ticket should link to the use case, either in email, or in the Use Cases and APIs doc. To get priority for a job, someone would write a use case to illustrate what they want, and include what the user interface would look like, either in email, or in the Use Cases document.


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:


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.

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"
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: Mon Nov 25 18:13:39 PST 2013