|
1 | | -How to release |
2 | | ----------------- |
3 | | - |
4 | | -Let’s assume that we want to make a new Xmipp version from the ‘devel’ |
5 | | -branch with a version name **X.YY.ZZ** where **X=3** (to keep the main |
6 | | -version number to be able to sort the version as usual. Also to keep the |
7 | | -name *xmipp3*), **YY=Year** of the release, **ZZ=Month** of release. |
8 | | -Also, we name the version following Greek gods/goddess (`Apollo, |
9 | | -Boreas… <https://www.gods-and-monsters.com/list-of-greek-gods-goddesses.html>`__), |
10 | | -see the `TAGging section |
11 | | -below <https://github.com/I2PC/scipion-em-xmipp/wiki/How-to-release-a-new-Xmipp-version#making-a-git-tag-and-promoting-the-code-to-master>`__. |
12 | | - |
13 | | -**Create the release notes** |
14 | | - |
15 | | -Add all the information about the release |
16 | | -`here <https://github.com/I2PC/xmipp/blob/devel/CHANGELOG.md>`__ |
17 | | - |
18 | | -**Schedule the releasing** |
19 | | - |
20 | | -Prepare everything, but post the release at the beginning of your |
21 | | -workday. |
22 | | - |
23 | | -Make release branches |
24 | | -^^^^^^^^^^^^^^^^^^^^^ |
25 | | - |
26 | | -Create a branch where freeze the code and fix some minor bug before to |
27 | | -upgrade the version for all Xmipp repositories. The usual name for that |
28 | | -branch is ``release-X.YY.ZZ``. > Branches with ‘release’ word are |
29 | | -protected, to unprotect it create a PR from an other branch and get the |
30 | | -aprove from other developer |
31 | | - |
32 | | - If some Xmipp repository has not to be uploaded (scipion-em-xmipp, |
33 | | - xmipp, xmippViz, xmippCore), please make this ``release-X.YY.ZZ`` |
34 | | - branch from the ``master`` one in order to make sure that the update |
35 | | - from other repos is compatible. In this way, we will also be able to |
36 | | - include some bug fixing during the release procedure. |
37 | | - |
38 | | -**Set the version to the code** |
39 | | - |
40 | | -There are three types of version tags. One is the plugin version (in |
41 | | -sync with pypi), other is the software version (related with the name of |
42 | | -the tgz hosted in the Scipion web) and, finally, the third is the |
43 | | -linking from the plugin to the software. |
44 | | - |
45 | | -- **Software version**: It must be set at ``$XMIPP_BUNDLE/xmipp`` –> |
46 | | - `XMIPP_VERSION=X.YY.ZZ <https://github.com/I2PC/xmipp/blob/f152af31ff8ab6400b77c7fb513aa3319901b3a3/xmipp#L41>`__. |
47 | | - This version is used when the software is compiled and the |
48 | | - ``xmipp_version`` is done, to create the end-of-installation token |
49 | | - (``$XMIPP_HOME/vX.YY.ZZ``) and when the bundle is created using |
50 | | - ``./xmipp tar ...`` with an automatic version. |
51 | | - |
52 | | -- **Linking version**:It must be set at |
53 | | - ``$XMIPP_BUNDLE/src/scipion-em-xmipp/xmipp3/__init__.py`` –> |
54 | | - `\_currentVersion = |
55 | | - ‘X.YY.ZZ’ <https://github.com/I2PC/scipion-em-xmipp/blob/c12a1115f268ec77edd34bf5c84e6ffad256a818/xmipp3/__init__.py#L41>`__. |
56 | | - This is used to find the binaries to install. This is also in sync |
57 | | - with `the pypi |
58 | | - versions <https://pypi.org/project/scipion-em-xmipp/#history>`__ |
59 | | - since this version is used when the pypi module is created and |
60 | | - uploaded. |
61 | | - |
62 | | -- **XMIPP_VERNAME** Replace devel for the name of the release |
63 | | - `here <https://github.com/I2PC/xmipp/blob/7e5aea662c93bbfbb6bcd3729850b95914a722f4/xmipp#L38>`__ |
64 | | - |
65 | | -- Replace the type_of_version at <https://github.com/I2PC/scipion-em-xmipp/blob/da42ebc37f85c1c39fcd7f6f2f9d1af1b9424c7a/xmipp3/__init__.py#L40>`__ |
66 | | - |
67 | | -- Review the status of each protocol (_devStatus), maybe some change |
68 | | - from New to Production, or production to updated… |
69 | | - |
70 | | -Creating the Xmipp software bundle |
71 | | -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
72 | | - |
73 | | -When the ``release-X.YY.ZZ`` branch is ready and all bugs seem fixed, |
74 | | -**we must do a Pull Request** for each Xmipp repository from |
75 | | -``release-X.YY.ZZ`` to ``master``. Once approved but **not merged yet**, |
76 | | -we can start with the release procedure. |
77 | | - |
78 | | - If the Pull Request contain conflicts, merge Master into your release |
79 | | - branch and resolve it. If the release only contain changes in the |
80 | | - plugin (not in the rest of the Xmipp repositories), you can go to the |
81 | | - next section below. |
82 | | - |
83 | | -Make sure that all is self-contained (keep in mind the rest of the |
84 | | -Xmipp’s repositories) and compatible with the current Scipion version. |
85 | | -To do that, go for a fresh compilation as follow |
86 | | - |
87 | | -(*We assume that the current version of Scipion is installed in |
88 | | -``$scipionMASTER``.*) |
89 | | - |
90 | | -:: |
91 | | - |
92 | | - git clone git@github.com:I2PC/xmipp.git xmipp2release |
93 | | - cd xmipp2release |
94 | | - |
95 | | - $scipionMASTER/scipion3 run ./xmipp all br=release-X.YY.ZZ N=8 |
96 | | - |
97 | | - $scipionMASTER/scipion3 uninstallp -p scipion-em-xmipp |
98 | | - git checkout release-X.YY.ZZ |
99 | | - $scipionMASTER/scipion3 installp -p ./xmipp2release/src/scipion-em-xmipp --devel |
100 | | - |
101 | | - rm -rf $scipionMASTER/software/em/xmipp |
102 | | - ln -s ~/xmipp2release/build $scipionMASTER/software/em/xmipp |
103 | | - |
104 | | - $scipionMASTER scipion3 test --grep xmipp |
105 | | - $scipionMASTER scipion3 test xmipp3.tests.XXX |
106 | | - $scipionMASTER scipion3 test xmipp3.tests.XXY |
107 | | - |
108 | | -If all goes well (no error should be in the tests, however we assume |
109 | | -some ones… (at least all those at Buildbot |
110 | | -`xmipp_bundle_devel <http://scipion-test.cnb.csic.es:9980/#/builders/50>`__ |
111 | | -and |
112 | | -`xmipp_devel <http://scipion-test.cnb.csic.es:9980/#/builders/19>`__) |
113 | | -then, we can make the Xmipp bundle. |
114 | | - |
115 | | -First ensures that the new version info is well set at the `Xmipp main |
116 | | -script <https://github.com/I2PC/xmipp/blob/45c18d3397bcf94581b7568ed583729dfa1cab9f/xmipp#L40-L43>`__. |
117 | | -If not, update it, commit the change and push it. **All should be pushed |
118 | | -to github since the bundle is done from the github/branch, instead of |
119 | | -you local version.** |
120 | | - |
121 | | -Then, we are able to create the bundle |
122 | | - |
123 | | -:: |
124 | | - |
125 | | - ./xmipp tar Sources br=release-X.YY.ZZ |
126 | | - |
127 | | -A ``xmippSrc-vX.YY.ZZ.tgz`` should be created, where ``YY.ZZ`` is |
128 | | -according to the version info set above. |
129 | | - |
130 | | -Test the archive in the Scipion |
131 | | -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
132 | | - |
133 | | -To test the archive, install new Scipion without Xmipp following the |
134 | | -guide |
135 | | -`here <https://scipion-em.github.io/docs/release-3.0.0/docs/scipion-modes/how-to-install.html>`__: |
136 | | - |
137 | | -:: |
138 | | - |
139 | | - python3 -m scipioninstaller -conda -noXmipp -noAsk scipion2ReleaseXmipp |
140 | | - |
141 | | -First thing that needs to be done is to install Xmipp plugin. |
142 | | - |
143 | | -:: |
144 | | - |
145 | | - ./scipion3 installp -p path/of/xmipp2release/src/scipion-em-xmipp --devel |
146 | | - |
147 | | -Once the plugin is installed, you should see Xmipp sources available for |
148 | | -installation: |
149 | | - |
150 | | -:: |
151 | | - |
152 | | - $ ./scipion3 installb |
153 | | - ... |
154 | | - xmippSrc 3.YY.ZZ.0[ ] |
155 | | - |
156 | | -Copy (overwrite) the source file ``xmippSrc-vX.YY.ZZ.tgz`` to the |
157 | | -*/software/em* path of the Scipion installation. Now install the |
158 | | -binaries and run some test to verify that everything works. Typical |
159 | | -problem is not matching version number in the *scipion-em-xmipp* plugin. |
160 | | - |
161 | | -:: |
162 | | - |
163 | | - ./scipion3 installb xmippSrc -j 8 |
164 | | - |
165 | | -If all seems fine means that bundle ``xmippSrc-vX.YY.ZZ.tgz`` is |
166 | | -compatible to work with the Scipion under ``$scipionMASTER`` and under |
167 | | -the plugin at ``~/xmipp2release/src/scipion-em-xmipp``, thus upload the |
168 | | -``.tgz`` to Nolan to be able to get it remotely. If you don’t know how |
169 | | -to do it, please `ask Scipion’s people <mailto:scipion@cnb.csic.es>`__ |
170 | | -(…/downloads/scipion/software/em) |
171 | | - |
172 | | -Creating the PyPi module |
173 | | -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
174 | | - |
175 | | -**Testing the installation with source archive from Nolan** |
176 | | - |
177 | | - |
178 | | -Before creation the Pypi module, **it is worth it to start a testing |
179 | | -stage** to be sure that all is working well. Take into account that, |
180 | | -once the Pypi module is uploaded, the current available version will |
181 | | -automaticly be this. |
182 | | - |
183 | | -Make sure that you remove existing Xmipp installation from the Scipion. |
184 | | -The easiest way is to do so via the Plugin manager. Make also sure that |
185 | | -there is no Xmipp archive in the ``software/em`` folder. |
186 | | - |
187 | | -Install the Scipion-em-xmipp plugin directly from the Github: |
188 | | - |
189 | | -:: |
190 | | - |
191 | | - ./scipion3 run pip install git+https://github.com/I2PC/scipion-em-xmipp.git@release-X.YY.MM # What is after '@' is the release branch. |
192 | | - ./scipion3 installb xmippSrc -j 8 |
193 | | - |
194 | | -During the installation, the source file archive should be downloaded |
195 | | -from Nolan. |
196 | | - |
197 | | -**Update PyPi module** |
198 | | - |
199 | | -Ensures that the `release |
200 | | -information <https://github.com/I2PC/scipion-em-xmipp/blob/fa78fc12536b814275b9a1790e3570f69bf5f0fd/setup.py#L43>`__ |
201 | | -is updated and match with those above. |
202 | | - |
203 | | -- **New way:** |
204 | | - |
205 | | -Merge in scipìon-em-xmipp the PR from release to master, one action will |
206 | | -manage the update to pypi, also will create a tag that we have to remove |
207 | | -(will be managed in the next step) ``git tag -d tagname`` |
208 | | -``git push --delete origin tagname`` > If you have no permissions to |
209 | | -push, clone each repository with |
210 | | -``git clone git@github.com:I2PC/scipion-em-xmipp.git`` |
211 | | -``git clone git@github.com:I2PC/xmippCore.git`` |
212 | | - |
213 | | -- **Old way:** |
214 | | - |
215 | | -When all is checked, create and upload the Pypi module by (check |
216 | | -`this <https://scipion-em.github.io/docs/docs/developer/creating-a-plugin#create-and-upload-distribution>`__ |
217 | | -for more information) Notice that you should have the Scipion virtual |
218 | | -environment active. |
219 | | - |
220 | | -:: |
221 | | - |
222 | | - cd src/scipion-em-xmipp |
223 | | - rm -rf dist/* # To clean the already uploaded modules |
224 | | - python setup.py sdist |
225 | | - twine upload dist/* -c "scipion-X.Y" |
226 | | - |
227 | | -after **``-c`` flag have to be the lowest Scipion’s compatible version** |
228 | | -(e.g. ``"scipion-3.0"``). |
229 | | -
|
230 | | -Making a git-TAG and promoting the code to MASTER |
231 | | -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
232 | | -
|
233 | | -After concluding the two section above, the new Xmipp version is already |
234 | | -released. Congrats! Publish it in mailing list, Twitter… but also we |
235 | | -want to keep this checkpoint in the git history by a TAG and we must |
236 | | -promote the code to the master branch: |
237 | | -
|
238 | | -:: |
239 | | -
|
240 | | - cd ~/xmipp2release |
241 | | - ./xmipp git tag 'vX.YY.ZZ-GreekGod' # replace GreekGod for one in the list below |
242 | | - ./xmipp git push origin 'vX.YY.ZZ-GreekGod' |
243 | | -
|
244 | | -we name the version following Greek gods (`Apollo, |
245 | | -Boreas… <https://greekgodsandgoddesses.net/gods/>`__) > If you have no |
246 | | -permissions to push, clone each repository with |
247 | | -``git clone git@github.com:I2PC/scipion-em-xmipp.git`` |
248 | | -``git clone git@github.com:I2PC/xmippCore.git`` |
249 | | - |
250 | | -Finally, **merge the rest 3 Pull Requests** to conclude the release! |
251 | | - |
252 | | -XmippTomo wants a release |
253 | | -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
254 | | - |
255 | | -XmippTomo wants a release syncronized with the release of Xmipp. To do |
256 | | -that: 1. Create a branch (release_3….) from devel 2. Edit the |
257 | | -`xmipptomo/init.py <https://github.com/I2PC/scipion-em-xmipptomo/pull/118/files#diff-a2df3bcb36a6120ad93308737e1c6ff4200936396e7aedd5b0debc62752c03e2>`__ |
258 | | -version number and writhe the same of the Xmipp, the last digit mst be |
259 | | -.0. 3. Be sure you have all the changes in your local path (git pull). |
260 | | -4. Create a PR from your branch to master. When it will be merged, the |
261 | | -action will create the tag and upload the version to pypi. |
262 | | - |
263 | | -Final considerations |
264 | | -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
265 | | - |
266 | | -Probably, you want all the bug fixings during the release procedure also |
267 | | -in the ``devel`` branch. |
268 | | - |
269 | | -To do so, **make a Pull Request from ``release`` to ``devel``**. Also |
270 | | -replace the name of the version for devel |
271 | | -`here <https://github.com/I2PC/xmipp/blob/7e5aea662c93bbfbb6bcd3729850b95914a722f4/xmipp#L38>`__ |
| 1 | +.. _creating-xmipp-release: |
| 2 | + |
| 3 | +============================= |
| 4 | +Steps to Create an Xmipp Release |
| 5 | +============================= |
| 6 | + |
| 7 | +.. contents:: Table of Contents |
| 8 | + :depth: 2 |
| 9 | + :local: |
| 10 | + |
| 11 | +Step 1: Define the Version Name |
| 12 | +------------------------------- |
| 13 | +- The version name follows the format **X.YY.ZZ**: |
| 14 | + - **X** = 3 (this keeps the main version number consistent to sort releases and maintain `xmipp3`). |
| 15 | + - **YY** = Year of the release. |
| 16 | + - **ZZ** = Month of the release. |
| 17 | +- Additionally, name the release after a Greek god or goddess. Check out the list at: https://www.gods-and-monsters.com/list-of-greek-gods-goddesses.html |
| 18 | +- Example: `3.24.06 - Boreas` (for a June 2024 release). |
| 19 | + |
| 20 | +Step 2: Update the `changelog.md` |
| 21 | +---------------------------------- |
| 22 | +1. Go through the changes in: |
| 23 | + - **xmipp** (includes `xmippcore`). |
| 24 | + - **scipion-em-xmipp**. |
| 25 | + - **xmippViz**. |
| 26 | +2. Follow the format used in previous releases. |
| 27 | + - This is crucial because the release automation uses these tags. |
| 28 | +3. Use pull requests as a reference to identify changes and describe them clearly. |
| 29 | + |
| 30 | +Step 3: Schedule the Release |
| 31 | +---------------------------- |
| 32 | +- Prepare all steps in advance. |
| 33 | +- Post the release at the **start of your workday** to address any issues promptly. |
| 34 | + |
| 35 | +Step 4: Check Tests |
| 36 | +-------------------- |
| 37 | +- Verify that **most tests pass**, or at least confirm that failing tests are consistent with previous results. |
| 38 | +- Use tools like **Buildbot** and **Hertz-Cinco** for validation. |
| 39 | + |
| 40 | +Step 5: Update Protocol Status |
| 41 | +------------------------------- |
| 42 | +- Review the `_devStatus` of each protocol: |
| 43 | + - Set to **PROD**, **NEW**, or **UPDATED** if applicable. |
| 44 | +- Consider deprecating protocols no longer in use or supported. |
| 45 | + |
| 46 | +Step 6: Announce the Release Freeze |
| 47 | +------------------------------------ |
| 48 | +- Announce at least **two weeks in advance** that no new changes will be merged into `devel`. |
| 49 | +- This stabilization period helps identify potential bugs in the `devel` branch. |
| 50 | + |
| 51 | +Step 7: Create Candidate Branches |
| 52 | +---------------------------------- |
| 53 | +- Name the release branches according to the release version (e.g., `release-3.24.06`). |
| 54 | + |
| 55 | +Step 8: Update Version Information |
| 56 | +----------------------------------- |
| 57 | +1. **In Xmipp**: |
| 58 | + - Update the name, version, and release date in: |
| 59 | + `https://github.com/I2PC/xmipp/blob/e72e2e9ea0ae824f60ded8b1f00b404d2c99d4d9/installer/constants/versions.py#L31` |
| 60 | + |
| 61 | +2. **In scipion-em-xmipp**: |
| 62 | + - Change the `devel` variable to `release` in: |
| 63 | + `https://github.com/I2PC/scipion-em-xmipp/blob/9881da0c6cdec69517e26fc025500d4940d44d0e/xmipp3/version.py#L28` |
| 64 | + - Update `_current_xmipp_tag` and `_currentBinVersion` accordingly. |
| 65 | + |
| 66 | +Step 9: Validate Release Branches Locally |
| 67 | +------------------------------------------ |
| 68 | +- Check out the release branches locally or on a test machine. |
| 69 | +- Verify: |
| 70 | + - Installation with and without Scipion. |
| 71 | + - Execution of a few tests. |
| 72 | + |
| 73 | +Step 10: Create Pull Requests |
| 74 | +------------------------------ |
| 75 | +- Open four pull requests: |
| 76 | + - **Release to master** for each relevant repository. |
| 77 | + |
| 78 | +Step 11: Document Changes |
| 79 | +-------------------------- |
| 80 | +- Compile a list of changed files, lines added, and other details from the PRs. |
| 81 | +- Document this in the Xmipp monitoring file. |
| 82 | + |
| 83 | +Step 12: Merge the Pull Requests |
| 84 | +--------------------------------- |
| 85 | +- Merge the four PRs. |
| 86 | + - This triggers the creation of release tags on GitHub. |
| 87 | + - In **scipion-em-xmipp**, it will also upload the package to PyPI. |
| 88 | + - Note: This is the most critical step to revert if issues arise. |
| 89 | + |
| 90 | +Step 13: Announce the Release |
| 91 | +------------------------------ |
| 92 | +- Share the release news via: |
| 93 | + - Email lists. |
| 94 | + - Discord. |
| 95 | + - Any other relevant platforms. |
| 96 | + |
| 97 | +Step 14: Consider XmippTomo |
| 98 | +---------------------------- |
| 99 | +- Evaluate whether **XmippTomo** needs a corresponding release. |
| 100 | + |
| 101 | +Step 15: PR from Release to Devel |
| 102 | +---------------------------------- |
| 103 | +- Create a pull request from `release` back to `devel`. |
| 104 | +- Revert the tags for `release` and `devel` in: |
| 105 | + - Xmipp. |
| 106 | + - scipion-em-xmipp. |
| 107 | + |
| 108 | +--- |
| 109 | + |
| 110 | +**That's it!** Now sit back, grab a coffee, and enjoy your shiny new release. 🚀 |
0 commit comments