This is an EPICS V4 working group internal document giving policies and procedures for releasing numbered versions of EPICS V4 software modules, and describing the release process.
This is the January 2016 version of the EPICS V4 Core Module Development and Release Guide. Previous document versions were specific to a particular release of the software, but this version is now meant to be generic.
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.
This document defines the policies that apply to all core EPICS V4 software modules produced by the EPICS V4 Working Group, and the procedures that are to be followed when creating official releases of those modules.
The policies described here have been developed for and agreed by the EPICS V4 Working Group, and apply to all core software modules developed for and formally published by the group.
The procedures documented here SHOULD be followed anyone involved in making officially numbered releases of the EPICS V4 software modules.
The EPICS V4 C++ and Java packages are released separately but share a common package version number, indicating that the available functionality for the two implementations should be similar. Each package is made up from a collection of individual modules which are developed and released in coordination with the V4 packaging process. However each module has its own independent module version number which is NOT REQUIRED to be related to the version number of the package it is published in.
When a package release is being developed, the version numbers of the modules that will make up that package are collected in a planning spreadsheet and used to generate the final package based on those module versions. Each module MUST be tagged in the module's source code repository with the module version number at the point when that version is finally ready to be published.
This use of independent version numbers for the modules permits bug-fix releases of individual modules to be made independently of other modules without having to follow the full packaging release process in all of them.
The group may also publish non-core modules such as example programs. These modules do not have to coordinated with the packaging of the core software, but SHOULD be released using module version numbers that follow the numbering format and policies described herein.
The version number for the EPICS V4 software packages MUST take one of the following forms:
4.major.minor 4.major.minor-suffix 4.major.minor.bugfix 4.major.minor.bugfix-suffix
majorincrements at every major package release.
minorincrements at every minor release, and is reset to zero whenever the
bugfixincrements at every bug-fix release, and is reset to zero whenever the
minorcomponent changes. This component and its preceding dot do not normally appear in the full version number when the component's value is zero.
‑suffixcomponent and its preceding hyphen are only present in pre-release and release candidate version numbers, never in a final package release version number.
‑suffixcomponent is used for development releases prior to a final package release version, and is normally either
‑pren(a numbered pre-release) or
‑rcn(a numbered release-candidate).
When printing or discussing a particular version number, the components
4.major.minor SHOULD always be included. The
‑suffix parts are
optional, but SHOULD be included if they they are needed to identify the
specific version of the software concerned.
‑BETA that was included with some previous
release version numbers is confusing and MUST NOT be used in the future.
Module version numbers and the related tags created in the module source code repositories MUST take one of these forms:
4.component from the package version number MUST NOT be included in the module version numbers or in the tags created in module source code repositories.
bugfixcomponent meanings are as described for the package version number above.
.bugfixcomponent MUST always be included, even when the number is zero.
Tags MUST be created in one of the above formats to mark the releases of each
module. Module developers MAY use the pre-release and release-candidate suffixes
if desired, or may use the
.bugfix component to indicate
subsequent module releases when working towards a package release. The final
module version number of any module used in an official packaged release MUST
not contain a
There are two kinds of software compatibility, at the source-code level (API) and the binary level (ABI). EPICS V4 releases will provide the following compatibility promises across release boundaries:
Neither ABI nor API compatibility is promised through a major release.
Developers SHOULD list and describe all public API changes that have occurred since the last major release in the Release Notes for the module, and MUST provide full documentation for the new API (usually using Doxygen or JavaDoc). If an API change requires significant changes to code that calls that API, an example showing both before and after code SHOULD be provided in or linked from the Release Notes. Code using the older API SHOULD NOT successfully compile against the new API if it will not run properly without modification.
Any incompatible change to the pvAccess network protocol MUST result in a major release of the software at its next release.
Forward API compatibility is promised through a minor release but not ABI compatibility, meaning that software written against the old version MUST be able to compile and run against the new one without changing its source code; recompilation of the software using the API is required against the new version though. Backwards API compatibility is not promised, but where there have not been any API changes an application written for a newer release SHOULD compile and run successfully against an earlier minor release version.
Developers MUST consider these compatibility requirements during minor release development. Tests SHOULD be written to check forward API compatibility for all modules where public API changes are being made, ensuring that older methods and routines remain fully functional in the modified implementation.
Other than changes required by the bug fix, both forward and backward compatibility MUST be provided for both the API and ABI through a bugfix release. For architectures that use shared libraries, it should only be necessary to replace the original shared libraries with the new ones, without recompiling any application that uses them. For architectures that statically link libraries into binary executables the link step will have to be re-run, although in this case it may be better to just rebuild the application completely.
Developers MUST consider these compatibility requirements while fixing bugs, and MUST NOT make any modifications to the names, call signatures or semantics of public API routines or methods unless those changes are needed to bring the implementation into line with the originally-published specification. If a bug cannot be fixed without making such a change, this policy requires that a minor release be made instead of a bug-fix release.
This section describes the process by which new versions of the EPICS V4 software packages will be created, tested and published to the wider EPICS community.
The following roles are used in the release process described below. Individuals may take multiple roles as necessary.
Different processes are appropriate for different kinds of releases. The working group may override these requirements for specific releases, but the stages below document the standard release process.
The working group or a designated Module Owner decides that a new version of the software is to be released, determines what changes it should contain, and whether this is to be a major, minor or bug-fix release. The release version number is agreed, and a Release Coordinator is nominated to manage the release process. Where the software to be released has a single Module Owner they would normally be expected to take on the role of the Release Coordinator. The dates for feature freeze and/or the final release may be discussed, but the process of finding and fixing bugs can easily thwart a specific final release deadline so such dates cannot be regarded as fixed at this stage.
In the period between the release decision and feature freeze, the Release Coordinator should consider the process described in this document and propose any changes desired to the Working Group for agreement. In conjunction with the Module Developers responsible for the software, the Release Coordinator should develop and publish to the working group a preliminary timetable for the remaining stages of the release process.
Module Developers should look for any remaining bugs that must/can be fixed in this release, and provide feedback to the Release Coordinator about the release timetable.
The Module Packagers should examine the release scripts and make any changes to them that are required due to either changes in the release process or in the software. This includes adding any new modules, removing any old ones that are no longer to be included, and adjusting any dependency information to match.
Feature freeze is announced for some specific time and date and is thus an instantaneous event, not a period of time. After that point, the software can be said to have been frozen.
All development work on new features for a release must have been completed by the freeze date; incomplete features should have been backed out and no additional feature branches should be merged afterwards. Only bug fixes and documentation updates should normally be committed between the freeze point and the final release.
If circumstances require it, the working group may agree to unfreeze a release in order to incorporate some additional features into the software. A new freeze date should be agreed at the same meeting and the release timetable for subsequent stages adjusted as appropriate.
After the freeze there will be a delay (normally 2 weeks but this may vary) before the first pre-release is made. Module Developers are expected to spend this period writing Release Notes, completing the documentation and testing their software to identify and fix any major bugs before the software is published to a wider audience. Module Packagers can use this time for testing and refining their release scripts.
The pre-release and release candidate stages described below represent the period after those specific versions of the packages have been created and published. The act of creating those packages is not instantaneous, past experience has shown that coordinating the final commits and tagging of the various core modules takes some time to do. In most cases individual modules depend on other modules in what can be considered a stream; downstream modules depend on upstream modules, but never the reverse. EPICS Base is considered to be the ultimate source of the stream that all the EPICS V4 core modules depend on.
Because of their inter-dependencies, upstream modules must be completed and tagged before any modules downstream of them can be completed. In order to streamline the packaging process, separate completion dates may be planned for the different modules for each stage, either individually or by grouping related modules together.
These are tagged, built and/or packaged versions of the code, created by the
Module Packager(s) that are published as such for testing by the wider EPICS
developer community. The first pre-release of a new package release should have
a version number with the suffix
‑pre1 with any subsequent
pre-releases numbering the suffix sequentially. Each pre-release version is
normally left open for 2 weeks after publication, and any significant bugs
discovered in this period may result in one or more additional pre-release
versions being created after the bugs have been fixed.
Integration Testers should attempt to build and use the packaged software in specific environments according to its documentation, and provide feedback and bug-reports based on this experience.
Module Developers should continue to run tests on the software in unusual configurations and on less common platforms during this period, and should also read through and fix errors and omissions in the documentation.
Once the group believes the software to be free of major bugs and fully
documented, the Release Coordinator nominates the next packaged version to be a
release candidate. The first of these should be given the suffix
‑rc1 with any subsequent versions numbering the suffix
sequentially. All release candidate versions should be publicized to the wider
EPICS user community for testing, and will normally be left open for 2
If significant bugs are discovered they must be fixed, and the Module Developers and Release Coordinator may then agree to publish another release candidate version with those fixes, or may revert to a pre-release version to ensure that any major bugs have been properly fixed.
Some time (usually 2 weeks) after a release candidate has been published with no major bug reports given for it in that period, the final release package should be created and published. Any remaining minor bugs that the group knows about but has decided not to fix should be documented in the list of Known Problems that accompanies the package release. The final release should be announced to the EPICS user community, accompanied by a set of Release Notes describing the major enhancements and changes that have been included.