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.
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.
The process is described by a list of practices and required documents, given in approximately the chronological order in which they are used.
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.
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 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.
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.
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.
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.