|
| 1 | +# Common Workflow Language Development and Release Process |
| 2 | + |
| 3 | +## Versioning |
| 4 | + |
| 5 | +CWL releases are semantically versioned. The number scheme is MAJOR.MINOR.PATCH. |
| 6 | + |
| 7 | +"Compatible versions" means that a CWL document can have its |
| 8 | +`cwlVersion` field trivially changed from one version to another, and |
| 9 | +the document will still validate and execute the same way. |
| 10 | + |
| 11 | +When making breaking changes such that an old version document cannot |
| 12 | +be trivially changed to a newer version, the MAJOR version must be |
| 13 | +increased, and MINOR and PATCH are reset to zero. An example of a |
| 14 | +breaking change is removing obsolete syntax. |
| 15 | + |
| 16 | +When adding features, such that an older version document with the |
| 17 | +same MAJOR version can be trivially changed to the newer `cwlVersion` |
| 18 | +(but not newer-to-older), the MINOR version must be increased, and the |
| 19 | +PATCH reset to zero. |
| 20 | + |
| 21 | +When making clarifications or text changes to an already-released |
| 22 | +specification that do not materially affect the document schema or |
| 23 | +execution semantics, the PATCH should be increased. The `cwlVersion` |
| 24 | +is unchanged in this case. |
| 25 | + |
| 26 | +Stable CWL releases are only referred to by their MAJOR.MINOR version. |
| 27 | + |
| 28 | +Development versions are indicated by taking the MAJOR.MINOR.PATCH of the |
| 29 | +version under development and adding "-devN" to the end, for example |
| 30 | +"-dev1". The development version should be incremented when making a |
| 31 | +breaking change or when requesting community review of the development |
| 32 | +version. There is no promise of compatability between "-dev" versions |
| 33 | +as a feature may undergo incompatible changes during development. |
| 34 | + |
| 35 | +When the version becomes the newest CWL specification, the "-devN" is |
| 36 | +removed. |
| 37 | + |
| 38 | +## Development process |
| 39 | + |
| 40 | +First, the decision is made whether the new release will be backwards |
| 41 | +compatible or not, and the new version number determined by |
| 42 | +incrementing the MAJOR, MINOR or PATCH part of the version. |
| 43 | + |
| 44 | +PATCH changes are made on the existing repository for the stable |
| 45 | +release. Version numbers in the specification document should be |
| 46 | +updated to the reflect the PATCH version. The `cwlVersion` is |
| 47 | +unchanged. |
| 48 | + |
| 49 | +For MAJOR and MINOR versions, create a new github repository |
| 50 | +"cwl-vMAJOR.MINOR" for the version series in the |
| 51 | +common-workflow-language organization. This repository will be a fork |
| 52 | +of the most recent stable release, with appropriate version numbers |
| 53 | +updated to the new development version (in the form |
| 54 | +"MAJOR.MINOR.0-dev1"). This includes the specification document and |
| 55 | +the `cwlVersion` of the documents in the test suite. |
| 56 | + |
| 57 | +The need for new features is determined by discussion with and |
| 58 | +contributions from the community. These may be tracked and discussed |
| 59 | +through github issues on the appropriate repository. |
| 60 | + |
| 61 | +Changes are proposed through pull requests against the development |
| 62 | +specification. Pull requests are merged by members of the development |
| 63 | +team that are authorized with commit access by the CWL leadership |
| 64 | +team. |
| 65 | + |
| 66 | +Changes to the specification should be accompanied with updates to the |
| 67 | +change log describing the change. The "-devN" version should be |
| 68 | +incremented following the guidelines above. Changes should also be |
| 69 | +accompanied by new conformance tests. |
| 70 | + |
| 71 | +Conformance tests may also be submitted on their own, if it is found |
| 72 | +that some feature has been overlooked by existing testing, or to |
| 73 | +ensure that a bug discovered in one implementation does not exist in |
| 74 | +other implementations. |
| 75 | + |
| 76 | +Proposed new features should be demonstrated in least one |
| 77 | +implementation to be be incorporated in the development specification. |
| 78 | +For stable release, there should be commitment to implement the |
| 79 | +feature by at least one other independent implementation. |
| 80 | + |
| 81 | +## Release process |
| 82 | + |
| 83 | +Once the development team feels that all outstanding issues for the |
| 84 | +release have been addressed, it is submitted to the leadership team |
| 85 | +for approval. |
| 86 | + |
| 87 | +A pull request is created that updates the version in the repository |
| 88 | +to remove the "-devN" suffix and the leadership team is notified about |
| 89 | +the proposed stable release. The leadership team registers their |
| 90 | +votes by adding comments on the pull request. A majority is |
| 91 | +sufficient to approve the specification although in practice if any |
| 92 | +concerns are raised they will generally be addressed with the goal of |
| 93 | +getting consensus. |
| 94 | + |
| 95 | +Following approval, the web site is updated to reflect the new stable |
| 96 | +release, the new release is announced on the relevant media, and a |
| 97 | +copy of the specification is uploaded to a research archive site such |
| 98 | +as Figshare or Zenodo to assign a DOI. |
| 99 | + |
| 100 | +Sometimes post-release fixes are necessary. Trivial changes (such as |
| 101 | +fixing typos) may be applied directly by the development team. More |
| 102 | +substantive changes to the text, such as clarifications or new |
| 103 | +conformance tests, require incrementing PATCH as discussed above, |
| 104 | +resulting in a new version that should be re-submitted for approval by |
| 105 | +the leadership team. |
0 commit comments