1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
Release Process
===============
Versioning
----------
There are two types of versioning in play in Patchwork: the version for
Patchwork itself (i.e. the code or *core*) and the version for the `REST
API <../api/rest>`.
Patchwork Code
~~~~~~~~~~~~~~
Since version 1.0, Patchwork has implemented a version of `Semantic
Versioning`__ . To summarise, releases take the format **MAJOR.MINOR.PATCH**
(or just **MAJOR.MINOR**). We increment:
1. **MAJOR** version when we make major UI changes or functionality updates
2. **MINOR** version when we make minor UI changes or functionality updates
3. **PATCH** version when we make make bug fixes, dependency updates etc.
In Git, each release will have a tag indicating the version number. In
addition, each release series has it's own branch called `stable/MAJOR.MINOR`
to allow backporting of bugfixes or security updates to older versions.
__ http://semver.org/
REST API
~~~~~~~~
The REST API also uses a variant of *Semantic Versioning*. To summarise, API
versions take the format **MAJOR.MINOR**. We increment:
1. **MAJOR** version when we make breaking changes to the API. This generally
means removing an API or fields in an API.
2. **MINOR** version when we add functionality in a backwards-compatible
manner. This generally means adding new fields and endpoint.
These version numbers are exposed via the API and it's possible to request a
specific version in the URL. Refer to the `API Guide <../api/rest>` for more
information.
Release Cycle
-------------
There is no cadence for releases: they are made available as necessary.
Supported Versions
------------------
Typically all development should occur on ``master``. While we will backport
bugfixes and security updates, we will not backport any new features. This is
to ensure stability for users of these versions of Patchwork.
Release Checklist
-----------------
The follow steps apply to all releases:
* Documentation has been updated with latest release version
* Documentation references latest supported version of Django
* 'alpha' tag has been removed from ``__version__`` in
``patchwork/__init__.py``
* Commit has been tagged with an `annotated tag`__. The tag should take the
form `v[MAJOR].[MINOR].[PATCH]`, e.g. `v2.0.1`. The message should read::
Version [MAJOR].[MINOR].[PATCH]
* A `GitHub Release`__, with text corresponding to an abbreviated form of the
release notes for that cycle, has been created
* An email describing the release and top-level overview of the changes has
been sent to the mailing list. Refer to the emails for `Patchwork v2.0.0`__
and `Patchwork v2.0.1`__ for examples.
The following only apply to full releases, or those where the **MAJOR** or
**MINOR** number is incremented:
* A new branch called ``stable/MAJOR.MINOR`` has been created from the tagged
commit
Once released, bump the version found in ``patchwork/__init__.py`` once again.
__ https://git-scm.com/book/en/v2/Git-Basics-Tagging
__ https://github.com/getpatchwork/patchwork/releases/new
__ https://lists.ozlabs.org/pipermail/patchwork/2017-August/004549.html
__ https://lists.ozlabs.org/pipermail/patchwork/2017-December/004683.html
Backporting
-----------
We will occasionally backport bugfixes and security updates. When backporting a
patch, said patch should first be merged into ``master``. Once merged, you can
backport by cherry-picking commits, using the ``-x`` flag for posterity:
.. code-block:: shell
$ git cherry-pick -x <master_commit>
There may be some conflicts; resolve these, uncommenting the `Conflicts` line
when committing::
Conflicts
patchwork/bin/pwclient
When enough patches have been backported, you should release a new **PATCH**
release.
Backport criteria
~~~~~~~~~~~~~~~~~
We consider bug fixes and security updates to the Patchwork code itself valid
for backporting, along with fixes to documentation and developer tooling. We do
not, however, consider the following backportable:
Features
Backporting features is complicated and introduces instability in what is
supposed to be stable release. If new features are required, users should
update their Patchwork version.
API changes
Except for bug fixes that resolve 5xx-class errors or fix security issues.
This also applies to API versions.
Requirement changes
Requirements on a stable branch are provided as a "snapshot in time" and, as
with features, should not change so as to prevent instability being introduced
in a stable branch. In addition, stable requirements are not a mechanism to
alert users to security vulnerabilities and should not be considered as such.
Users of stable branches should either rely on distro-provided dependencies,
which generally maintain a snapshot-in-time fork of packages and selectively
backport fixes to them, or manage dependencies manually. In cases, where using
a distro-provided package necessitates minor changes to the Patchwork code,
these can be discussed on a case-by-case basis.
|