Warning, /utilities/krusader/doc/development/release-howto.md is written in an unsupported language. File is not indexed.
0001 # Krusader Release Howto 0002 0003 This is a step-by-step release guide intended to streamline release process. 0004 Don't follow this blindly though. Think, test and improve the guide as the process changes! 0005 0006 Release managers are required to be a part of the Krew with a Developer role. 0007 It implies that you set the developer access up already. 0008 0009 0010 ## Overall release process 0011 0012 * [Create an issue](#create-an-issue) to claim yourself as a release manager. 0013 * Based on the discussion in the issue, set an appropriate [feature freeze](#feature-freeze) for the release. 0014 * Agree on the approximate release date. 0015 * Wait for changes to be reviewed and pushed. 0016 * Discuss and [pick a release name](#release-name) in case of a major or a minor release. 0017 * [Create a release branch](#create-a-release-branch) if needed. 0018 * Update or ask to [update the documentation](#update-the-documentation), including features for a major or a minor release. 0019 * 3 weeks before the release: propose the release date, [update the docs and AppStream files](#code-review-documentation-and-appstream-files). 0020 * 2 weeks before the release: [declare a string and doc freeze](#declare-a-string-and-doc-freeze). 0021 * [Update change logs and news](#code-review-changelog-and-news-update) in the meantime. 0022 * Prepare review: [version update](#code-review-version-bump). 0023 * Prepare review: [website update](#code-review-website-update). 0024 * [Prepare the environment](#environment) and practice if needed. 0025 * On the release date [follow the steps](#on-the-release-date) to prepare and release the package. 0026 * [Wrap up](#wrap-up): check bugzilla and merge the changes to master. 0027 0028 See also [the KDE community guide for releasing software](https://community.kde.org/ReleasingSoftware). 0029 0030 0031 ## Create an issue 0032 0033 Create an [issue](https://invent.kde.org/utilities/krusader/-/issues) to claim yourself as a release manager. 0034 Ask if there are any outstanding issues, code reviews, unpublished work that devs want to include into the release. 0035 Wait for a week to gather replies. 0036 0037 Examples: 0038 [v2.8.0](https://invent.kde.org/utilities/krusader/-/issues/22) was requested externally, so it's not an ideal example. 0039 Check the email threads from before-GitLab era: 0040 [v2.7.1](https://groups.google.com/d/msg/krusader-devel/a3OdfBDv4K0/b_S_uap-BgAJ), 0041 [v2.7.0](https://groups.google.com/d/msg/krusader-devel/TMIUqY1gyRg/_Vl7J64aBAAJ). 0042 0043 0044 ## Feature freeze 0045 0046 Discuss the proposed changes in the issue, set a feature freeze for the release. 0047 It means no new features should be included to the release later 0048 except for the agreed upon at this stage or bug fixes. 0049 Agree on the approximate release date. 0050 0051 Examples: 0052 [v2.8.0](https://invent.kde.org/utilities/krusader/-/issues/22#note_499898), 0053 [v2.7.1](https://groups.google.com/d/msg/krusader-devel/a3OdfBDv4K0/G2YXjGtmBwAJ), 0054 [v2.7.0](https://groups.google.com/d/msg/krusader-devel/TMIUqY1gyRg/HVwioll8AAAJ). 0055 0056 0057 ## Release name 0058 0059 Discuss and pick a release name in case of a major or a minor release. 0060 Bug fix releases carry the release name over (for example, v2.7.x are all "Peace of Mind"). 0061 See [the history of the release names](https://docs.kde.org/stable5/en/krusader/krusader/release_overview.html) 0062 and don't repeat, it's not fun. 0063 0064 Examples: 0065 [v2.8.0](https://invent.kde.org/utilities/krusader/-/issues/22#note_499898), 0066 [v2.7.0](https://groups.google.com/d/msg/krusader-devel/TMIUqY1gyRg/HVwioll8AAAJ). 0067 0068 0069 ## Create a release branch 0070 0071 In case you're doing a minor or major release (i.e. 2.7 -> 2.8 or 2.8 -> 3.0), `stable` branch needs to be remapped. 0072 0073 For example, you are going to do 2.7 -> 2.8. Then 0074 1. First create a branch at the same point as `stable` to mark a past release branch. Name it `2.7`. 0075 2. Hard reset stable to `master` 0076 3. Create a commit in `master` updating the app version to `2.9.0-dev` (`stable` should keep previous master version which is `2.8.0-dev`, so no commit is needed) 0077 4. Push `master`, `2.7` to the remote. 0078 5. Since `stable` is protected from non-fast-forward updates, first delete the remote branch with `git push origin :stable`. Then push `stable` to the remote. 0079 0080 Now you are ready for the release. 0081 0082 In case you're doing patch version update (i.e. 2.7.1 -> 2.7.2), no update to stable branch is needed. 0083 0084 0085 ## Update the documentation 0086 0087 Update or ask to update the documentation. 0088 Check if changes made from the previous release have been documented. 0089 0090 Update features for a major or a minor release in the `doc/handbook/features.docbook`. 0091 0092 Examples: 0093 [v2.8.0](https://invent.kde.org/utilities/krusader/-/merge_requests/108), 0094 [v2.7.0](https://phabricator.kde.org/D12531?vs=on&id=33125). 0095 0096 0097 ## Code Review: Documentation and AppStream files 0098 0099 Propose the release date. 0100 This should be at least 3 weeks out from current date as we need to put the date into the docs, 0101 this change has to be reviewed, approved and merged, 0102 and we need to allow at least 2 weeks for translators to update the strings. 0103 0104 Update the following files with new release version, date and name (if applicable): 0105 * `app/org.kde.krusader.appdata.xml` 0106 * `doc/handbook/index.docbook` 0107 * `doc/handbook/release-overview.docbook` 0108 0109 **This must be pushed before doc freeze email.** 0110 0111 Examples: 0112 [v2.8.0](https://invent.kde.org/utilities/krusader/-/merge_requests/109), 0113 [v2.7.2](https://phabricator.kde.org/D22982). 0114 0115 0116 ## Declare a string and doc freeze 0117 0118 Declare a string and doc freeze at least 2 weeks before the release date 0119 by sending an email to kde-i18n-doc@kde.org and notifying devs on the issue. 0120 0121 Subject: `String and doc freeze for Krusader stable branch` 0122 0123 Body template: 0124 ``` 0125 Hi Localization team, 0126 0127 Krusader stable branch is now in the string and doc freeze mode. 0128 We plan to release v{VERSION} on {DATE}. 0129 Please update the translations accordingly. 0130 0131 Thanks, 0132 {YOUR_NAME} on behalf of Krusader team. 0133 ``` 0134 0135 Examples: 0136 [v2.7.1](https://groups.google.com/forum/#!topic/krusader-devel/Fe5bOeTbCCo). 0137 0138 0139 ## Code Review: ChangeLog and NEWS update 0140 0141 Update the following files accordingly: 0142 * `Changelog` 0143 * `NEWS` 0144 * `doc/ChangeLog` 0145 0146 Search in git log for changelog messages and add them to the `ChangeLog` file: 0147 ``` 0148 cd krusader 0149 LAST_VERSION="vX.Y.Z" 0150 git log $LAST_VERSION.. | grep 'FIXED:\|ADDED:\|UPDATED:\|CHANGED:\|REMOVED:' | sort 0151 ``` 0152 0153 Add changes from bugzilla bug reports and code reviews manually if necessary. 0154 0155 Examples: 0156 [v2.8.0](https://invent.kde.org/utilities/krusader/-/merge_requests/107), 0157 [v2.7.1](https://phabricator.kde.org/D14619?id=39104), 0158 [v2.7.0](https://phabricator.kde.org/D12818?id=33973). 0159 0160 0161 ## Code Review: Version bump 0162 0163 Update the following files with new release version, date, name (if applicable): 0164 * `CMakeLists.txt` 0165 * `README` 0166 0167 **Verify that the version is building without warnings for both Debug and Release targets. 0168 Verify it's running correctly and you don't see any obvious problems. 0169 Do this ahead of time to be able to fix problems early!** 0170 0171 Commit message template: 0172 ``` 0173 Released v{X.Y.Z} 0174 0175 Resolves #{N}. 0176 0177 Discussion: {LINK} 0178 ``` 0179 0180 Here `N` is the index of an issue about the release. 0181 The `Resolves` tag will close the issue once you [merge](#merge-new-version-tag-to-master) the release tag 0182 into the `master` as the last step of this process. 0183 0184 Examples: 0185 [v2.8.0](https://invent.kde.org/utilities/krusader/-/merge_requests/110). 0186 0187 0188 ## Code Review: Website update 0189 0190 Update the following pages: 0191 * `get-krusader/release-archive/index.html` 0192 * `get-krusader/index.html` 0193 * `release/{VERSION}/changelog.txt` 0194 * `release/{VERSION}/release_notes.txt` 0195 0196 Copy release notes and changelog from NEWS and ChangeLog accordingly. 0197 0198 Also check if website copyright year needs to be updated. 0199 0200 Examples: 0201 [v2.8.0](https://invent.kde.org/websites/krusader-org/-/merge_requests/10). 0202 0203 0204 ## Environment 0205 0206 Prepare this before the release date to be ready. 0207 It doesn't hurt to practice [the release steps](#on-the-release-date) ahead of time. 0208 0209 ### First time setup 0210 ``` 0211 mkdir -v krusader-release-env && cd krusader-release-env 0212 git clone git@invent.kde.org:utilities/krusader.git 0213 git clone git@invent.kde.org:sdk/releaseme.git 0214 ``` 0215 0216 ### Refresh 0217 ``` 0218 cd krusader-release-env 0219 cd krusader && git checkout stable && git pull ; cd .. 0220 cd releaseme && git pull ; cd .. 0221 ``` 0222 0223 0224 ## On the release date 0225 0226 ### Verify the branch 0227 0228 Starting from version 2.7.1 we release only from the `stable` branch. 0229 In your dev environment do 0230 ``` 0231 cd krusader && git checkout stable && git pull 0232 ``` 0233 0234 Verify that ChangeLog and NEWS update is pushed or push it. 0235 0236 ### Commit and push version updates 0237 0238 Apply the version bump commit. Tag it: 0239 ``` 0240 VERSION=`cat CMakeLists.txt | grep 'set(VERSION' | awk -F '"' '{print $2; }'` 0241 echo $VERSION # verify the version 0242 git tag -a v${VERSION} -m "Tagging krusader-${VERSION}" 0243 ``` 0244 0245 Don't push it right away! First edit `CMakeLists.txt` to change version to development version 0246 (for example, for v2.7.1 release put `2.7.2-dev` there). Commit. Check everything is good: 0247 ``` 0248 git log 0249 ``` 0250 0251 Now push with tags: 0252 ``` 0253 git push --follow-tags 0254 ``` 0255 0256 This way ensures there are no commits in between version bumps. 0257 0258 ### Refresh the release environment 0259 0260 See [Refresh Environment](#refresh). The following steps assume you are in `krusader-release-env`. 0261 0262 ### Create tarball 0263 0264 The `tarme` script from the `releaseme` repo is intended as a universal snapshot creator. 0265 Let's run it: 0266 ``` 0267 mkdir -v tarme-wdir && cd tarme-wdir 0268 ../releaseme/tarme.rb --origin stable --version $VERSION krusader 0269 ``` 0270 This will fetch the latest code from the `stable` branch, fetch the latest localization files, 0271 create an html report with localization status and create the tarball. 0272 0273 Check the report but *don't use the tarball*. 0274 We don't need the latest from the branch as it has the commit with the `*-dev` version bump 0275 and potentially other commits on top of it if somebody pushed to the branch after you. 0276 Until tarme has a parameter to use a tag or a commit hash, the tarball is useless for the release purpose. 0277 0278 As of October 2022, localization files are injected into the `krusader` repo, 0279 both `master` and `stable` branches. 0280 It means the repo is self-contained and we can create the snapshot manually: 0281 0282 ``` 0283 cd .. # go back to krusader-release-env 0284 mkdir -v tarball-wdir && cd tarball-wdir 0285 git clone ../krusader 0286 cd krusader/ 0287 git reset --hard v${VERSION} 0288 rm -rf .git 0289 cd .. 0290 mv krusader krusader-${VERSION} 0291 tar -cJf krusader-${VERSION}.tar.xz krusader-${VERSION} 0292 ``` 0293 0294 It's worth checking the difference between the two ways we created the snapshots: 0295 ``` 0296 cd .. 0297 diff -Naur tarme-wdir/krusader-${VERSION} tarball-wdir/krusader-${VERSION} > tarme.patch 0298 ``` 0299 0300 Now let's clean up to avoid mistakes: 0301 ``` 0302 rm -rf tarme-wdir 0303 cp tarball-wdir/krusader-${VERSION}.tar.xz . 0304 ``` 0305 0306 ### Test the package 0307 0308 **Corrupted translated documentation can break compiling, it's mandatory to do this step!** 0309 0310 Unpack: 0311 ``` 0312 tar -xJf krusader-${VERSION}.tar.xz 0313 ``` 0314 0315 Build and run: 0316 ``` 0317 mkdir -v build-${VERSION} && cd build-${VERSION} && cmake -DCMAKE_INSTALL_PREFIX=../install-${VERSION} -DQT_PLUGIN_INSTALL_DIR=../install-${VERSION} ../krusader-${VERSION} && make -j8 && make install ; cd .. 0318 0319 ./install-${VERSION}/bin/krusader 0320 ``` 0321 0322 Go to `Help -> About Krusader` and verify the version. 0323 0324 ### Upload the package to a KDE server 0325 0326 ``` 0327 curl -T krusader-${VERSION}.tar.xz ftp://upload.kde.org/incoming/ 0328 ``` 0329 0330 ### Create a Sysadmin Request 0331 0332 Send a ticket for KDE Sysadmins asking to publish the package. 0333 The tickets are still created on Phabricator until the task system is migrated to GitLab. 0334 To create a ticket go to [Tasks](https://phabricator.kde.org/maniphest/), 0335 in the top right corner click `Create Task -> + New Sysadmin Request`. 0336 0337 Compute the hash to report: 0338 ``` 0339 sha256sum krusader-${VERSION}.tar.xz 0340 ``` 0341 0342 Subject: `Krusader v{VERSION} release` 0343 0344 Priority: `Normal` 0345 0346 Body template: 0347 ``` 0348 Dear Sysadmins, 0349 0350 Please release a package for a new Krusader version to download.kde.org! 0351 0352 The package is uploaded to ftp://upload.kde.org/incoming/. 0353 0354 Destination: https://download.kde.org/stable/krusader/{VERSION}/krusader-{VERSION}.tar.xz 0355 SHA256: {SHA256} 0356 0357 Please also add this release to the list of Krusader versions on bugs.kde.org. 0358 0359 Thanks, 0360 {YOUR_NAME}. 0361 ``` 0362 0363 We ask them to add versions on Bugzilla since the *editcomponents* permission is needed. 0364 This permission allows to change settings for ALL projects. 0365 Therefore only sysadmins can do this and nobody of the Krusader devs. 0366 0367 Example tickets: 0368 [v2.8.0](https://phabricator.kde.org/T15998), 0369 [v2.7.1](https://phabricator.kde.org/T9350). 0370 0371 ### Update the package checksum in the website change 0372 0373 Earlier, when you create the CR for the website change, you didn't know the hash of the package since you haven't created a package yet. Now you know it, and it's a good time to update it while you wait for response from admins. 0374 0375 Example checksum updates: 0376 [v2.8.0](https://invent.kde.org/websites/krusader-org/-/merge_requests/10#note_565720). 0377 0378 ### Wait for the package to propagate on KDE servers 0379 0380 Once admins upload the package, they will close the ticket. You need to wait until you see some mirrors become available and then you can distribute the package. 0381 0382 ### Update the Krusader website 0383 0384 Simply push your changes to krusader.org repository and they'll become available as soon as a recurrent deployment job discovers the change and publishes the update. May take from a few minutes to a few hours (sometimes the recurrent job is down) - usually it's very quick. If your changes are not deployed in 2 hours, create a sysadmin ticket about it. 0385 0386 Example merges: 0387 [v2.8.0](https://invent.kde.org/websites/krusader-org/-/commit/db5d6d8b1f47a30d0b65fe5ea7b743a2be6ae703). 0388 0389 ### Send a letter to mailing lists 0390 0391 Once the website is updated, send a letter to the following mailing lists: 0392 * krusader-devel@googlegroups.com 0393 * krusader-users@googlegroups.com 0394 * krusader-news@googlegroups.com 0395 * kde-announce-apps@kde.org 0396 0397 Please get the permission to post ahead of time. 0398 0399 Example letters: 0400 [v2.8.0](https://groups.google.com/g/krusader-users/c/aD6GqHUKjGM), 0401 [v2.7.2](https://groups.google.com/g/krusader-users/c/7terZtDa8Ss). 0402 0403 0404 ## Wrap up 0405 0406 ### Check if bugzilla is updated accordingly 0407 0408 [Click here](https://bugs.kde.org/enter_bug.cgi?product=krusader) and check if new version is present in the list. 0409 0410 ### Merge new version tag to master 0411 0412 Since `stable` contains changes not present in `master` (ChangeLog and documentation changes at least), 0413 you need to deliver them to the `master` branch. 0414 Merge the release tag into the branch 0415 0416 ``` 0417 git checkout master 0418 git pull 0419 git merge --no-ff --no-commit --no-log v${VERSION} 0420 ``` 0421 0422 You may see a lot of conflicts and changes in localization-enabled files, 0423 such as in `po` dir and `.desktop`, `.appdata.xml` files. 0424 This happens since the branches have separate localization injection streams. 0425 There is a helper script that restore these files to the state before the merge, 0426 with the exception to `.appdata.xml` that often contains version changes 0427 and requires attention. 0428 0429 ``` 0430 ./tools/restore-l10n-files.sh 0431 ``` 0432 0433 Resolve remaining conflicts, keeping the Krusader version that is in `master`, and stage, then 0434 0435 ``` 0436 git commit -m "Merged v${VERSION} updates" 0437 git push 0438 ``` 0439 0440 [Check](https://invent.kde.org/utilities/krusader/-/issues) that the issue 0441 about the release is closed by the push 0442 (in case you used `Resolves` tag [here](#code-review-version-bump)). 0443 If not, close it manually. 0444 0445 Example merges: 0446 [v2.8.0](c80c9ec0) + [fix](f7be3730), 0447 [v2.7.1](8d5946a1).