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 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.
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 tracking mechanism is to use SourceForge (SF) tickets. Each kind of item tracked above will be tracked by a SF ticket type.
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|
|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.
Working group participants are expected to:
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.
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.
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.