1#************************************************************** 2# 3# Licensed to the Apache Software Foundation (ASF) under one 4# or more contributor license agreements. See the NOTICE file 5# distributed with this work for additional information 6# regarding copyright ownership. The ASF licenses this file 7# to you under the Apache License, Version 2.0 (the 8# "License"); you may not use this file except in compliance 9# with the License. You may obtain a copy of the License at 10# 11# http://www.apache.org/licenses/LICENSE-2.0 12# 13# Unless required by applicable law or agreed to in writing, 14# software distributed under the License is distributed on an 15# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16# KIND, either express or implied. See the License for the 17# specific language governing permissions and limitations 18# under the License. 19# 20#************************************************************** 21 22Adapting version after a release of an office 23============================================= 24After a release the entries in cli_ure/version/version.txt must be changed to reflect the versions 25of the assemblies at the time of the release. Please refer to the document at 26http://udk.openoffice.org/common/man/spec/assemblyversioning.html 27for more information about versioning of assemblies. 28 29 30Step 1: Remove old office installations. 31 32To do this, deinstall all offices, 33and make sure that there are no assemblies installed in the Global Assembly Cache (GAC). The GAC 34is contained in C:\Windows\assembly. Change C:\Windows according to your windows installation. 35Use the Windows Explorer to view the contents of the GAC. Are there any of the following assemblies 36installed: 37 38cli_uretypes.dll 39cli_basetypes.dll 40cli_cppuhelper.dll 41cli_ure.dll 42cli_oootypes.dll (build in unoil) 43 44policy.x.y.cli_uretypes.dll 45policy.x.y.cli_basetypes.dll 46policy.x.y.cli_ure.dll 47policy.x.y.cli_cppuhelper.dll 48policy.x.y.cli_oootypes.dll (build in unoil) 49 50The "x" and "y" in the names of the policy assemblies are to be replaces by version numbers. At the 51time of writing the real names are: 52 53policy.1.0.cli_uretypes.dll 54policy.1.0.cli_basetypes.dll 55policy.1.0.cli_ure.dll 56policy.1.0.cli_cppuhelper.dll 57policy.1.0.cli_ootypes.dll (build in unoil) 58 59After deinstalling the offices, there should none of them remain in the GAC. If there are some, then 60try to remove them by clicking on them an choose uninstall from the context menu of the mouse. 61 62Step 2: Install the office of the last release (respin when using staroffice) 63 64Step 3: Determine the versions of the assemblies 65 66Use the Windows Explorer to view the contents of the Windows\assembly directory. Locate the assemblies 67and policy assemblies. See step 1 for the names of those assemblies. Take down the version number as 68can be found in the version column, which is usually right next to the name column. 69 70Step 4: Changing the versions in the cli_ure module. 71 72Open the file cli_ure\version\version.txt. 73The file contains name/value pairs, such as:CLI_URETYPES_NEW_VERSION=1.0.3.0. 74The first part of the names represent the assemly which they are referring to. So obviously 75entries starting with CLI_URETYPES refer to the cli_uretypes.dll. Entries which contain the part "POLICY" refer 76to the policy assembly. For example: 77CLI_URETYPES_POLICY_VERSION refers to the policy assembly for cli_uretypes which is named 78policy.1.0.cli_uretypes.dll 79 80The versions may already have been incremented because someone has changed code after the 81last release. So if a version from version.txt is greater then the one of the respective 82assembly in the GAC then leave it at that. 83 84The values have to be adjusted as follows: 85 86XYZ_NEW_VERSION : increse the value of the version 87GAC. "XYZ_" would be "CLI_URETYPES", "CLI_URE", etc. 88XYZ_OLD_VERSION : must be changes so that the right version part is one less than 89XYZ_NEW_VERSION. For example 90 91CLI_URETYPES_NEW_VERSION=1.0.[3].0 92CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.[2].0 93 94The affected part is marked by the brackets. 95 96XYZ_POLICY_VERSION: change the version according to the version of the policy assembly from the 97GAC. 98 99XYZ_POLICY_ASSEMBLY: remain unchanged. 100 101Commit the changes and rebuild the project. 102 103Step 5: Changing the versions in the unoil module 104 105The unoil module builds the cli_oootypes.dll which contains the office types (offapi). Change the contents 106of unoil/climaker/version.txt similar to the versions.txt in this module. Then rebuild the module 107 108//====== 109The automatic test in cli_ure/qa/versioning should be extended. See the readme.txt in that directory 110for more information. 111//===== 112 113 114 115 116 117 118How does the version mechanism works 119==================================== 120 121The assemblies which are build in this project have a strong name and hence a version. The version should 122be increased whenever something was fixed or the code has changed in any way. For further information 123have a look at 124http://udk.openoffice.org/common/man/spec/assemblyversioning.html 125 126The versions of all assemblies are contained in cli_ure/version/version.txt. This is the place where 127the versions are changed. This will happen under two circumstances. First, the versions are 128adjusted AFTER an office was released. The version.txt must then contain the versions at the 129time of the release. Second, when something was fixed. Then a version should be changed unless 130this has already be done for the next release. Please look at the document mentioned further 131above. 132 133If new published UNO types have been added since the last release (product update) then the 134minor version of cli_uretypes.dll should be incremented. When building the version directory, a script 135is run that recognizes this and writes a cliureversion.mk file in the bin directory. 136cliureversion.mk contains all the entries of version.txt. The versions have been incremented 137by the script. The script obtains the information of new types from unotype_statistics.txt 138which is build in offapi. 139 140The contents of cliureversion.mk is used when building the assemblies in this project. It 141is also delivered so that instset_native (or instsetoo_native) can use it when building 142the installation sets. 143 144 145The contents of version.txt 146=========================== 147The entries in version.txt are needed for building the assemblies and for building the 148installation set (msi database). 149 150For every assembly exist four 151entries. For example: 152 153CLI_URETYPES_NEW_VERSION=1.0.3.0 154CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.2.0 155CLI_URETYPES_POLICY_VERSION=3.0.0.0 156CLI_URETYPES_POLICY_ASSEMBLY=policy.1.0.cli_uretypes 157 158The meaning of these entries is the following: 159 160CLI_URETYPES_NEW_VERSION represents the current version of the assembly. 161 162CLI_URETYPES_OLD_VERSION represents a range of former versions (which were compatible). 163It has to be placed in the 164cli_uretypes.config XML file which is part of the policy assembly. This is done automatically. 165The XYZ_OLD_VERSION and XYZ_NEW_VERSION values are used for the binding redirection of 166the policy file. 167 168CLI_URETYPES_POLICY_VERSION represents the version of the policy file. 169 170CLI_URETYPES_POLICY_ASSEMBLY represents the name of the policy file. 171 172Please refer to the document at 173http://udk.openoffice.org/common/man/spec/assemblyversioning.html 174about how the versions have to look like. 175 176When the minor version is changed, which is the third number from the left, the 177"old version" and the policy version must be changed as well. Using the former example, 178an incremented version would look like this: 179CLI_URETYPES_NEW_VERSION=1.0.4.0 180CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.3.0 181CLI_URETYPES_POLICY_VERSION=4.0.0.0 182CLI_URETYPES_POLICY_ASSEMBLY=policy.1.0.cli_uretypes 183 184If the major version changed we would have these values: 185CLI_URETYPES_NEW_VERSION=2.0.0.0 186CLI_URETYPES_OLD_VERSION=2.0.0.0-2.0.0.0 187CLI_URETYPES_POLICY_VERSION=1.0.0.0 188CLI_URETYPES_POLICY_ASSEMBLY=policy.2.0.cli_uretypes 189 190Because a change of a major is only done if the code has changed incompatibly, we must not 191redirect old client code to the new assembly. Actually we would not need a policy file here. 192The name of the policy file has changed as well so as to refer to the new version. Since 193the name is new and refers to the version 2 auf cli_uretypes, we can start with the policy version 194from 1. 195 196The next compatible change would require to change the version to these: 197CLI_URETYPES_NEW_VERSION=2.0.1.0 198CLI_URETYPES_OLD_VERSION=2.0.0.0-2.0.1.0 199CLI_URETYPES_POLICY_VERSION=2.0.0.0 200CLI_URETYPES_POLICY_ASSEMBLY=policy.2.0.cli_uretypes 201 202 203Automatic incrementation of the version 204======================================= 205Currently switched off! See cli_ure/version/makefile.mk 206The automatic incrementation of the version this is done when new published types have been 207introduce between two releases.In cli_ure/version/makefile.mk the script 208cli_ure/source/scripts/increment_version.pl 209is run which creates the cliureversion.mk with the new versions. This automatism only changes 210the version parts which have the meaning of a compatible change. Which versions are to be 211incremented is contained in cli_ure/version/incversions.txt. It contains, for example these entries: 212 213CLI_URETYPES_NEW_VERSION 214CLI_URETYPES_OLD_VERSION 215CLI_URETYPES_POLICY_VERSION 216 217The names are exactly the same as in version.txt. The script knows how to increase the version 218of the different types: 219 220Entries ending on _NEW_VERSION: The third number from the left is incremented. 221Entries ending on _OLD_VERSION: The third number from the left of the second version is incremented. 222Entries ending on _POLICY_VERSION: The first number from the left is incremented. 223 224For example, the versions in version.txt are: 225CLI_URETYPES_NEW_VERSION=1.0.4.0 226CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.3.0 227CLI_URETYPES_POLICY_VERSION=4.0.0.0 228 229If new types have been added the script would create these entries in cliureversion.mk 230CLI_URETYPES_NEW_VERSION=1.0.5.0 231CLI_URETYPES_OLD_VERSION=1.0.0.0-1.0.4.0 232CLI_URETYPES_POLICY_VERSION=5.0.0.0 233 234As one can see from the incversions.txt, the versions of the cli_ure.dll and cli_cppuhelper.dll 235are also changed. This is because these are dependent on cli_uretypes.dll. 236 237 238Further notes on increasing the assembly versions 239================================ 240Changing a version for one assembly means changing 241at least the XYZ_NEW_VERSION, XYZ_OLD_VERSION and XYZ_POLICY_VERSION. In case of an incompatible 242change, that is one of the first two numbers of the version has been changed, the XYZ_POLICY_ASSEMBLY 243must also be changed. 244 245When changing a version of an assembly then the versions of the assemblies which depend on it should 246be changed as well. For example, when changing the version of cli_uretypes.dll, then the versions of 247cli_ure.dll and cli_cppuhelper.dll should be changed as well. One can use idlasm.exe to see which 248assemblies are referenced by an assembly. The information is contained in the assemblie's manifest. 249 250If one would not change the versions of the dependent dlls then one would risk that an assembly 251has the same old version but references a different assembly. For example, say we have a 252cli_uretypes.dll with version 1 and a cli_ure.dll with version 1. cli_ure.dll references version 1 of 253cli_uretypes.dll. Now the version of cli_uretypes.dll changes to version 2 and its policy assembly is 254adapted so that all code that uses version 1 now uses version 2. This would also allow cli_ure.dll 255o run with the new cli_uretypes.dll. If now cli_ure.dll is build, then it would reference 256cli_uretypes.dll version 2, because our build environment does not keep the older assembly. The old 257cli_uretypes.dll version 1 was replaced by version 2. cli_ure.dll now references cli_uretypes.dll version 2 258but still has the old version. 259 260 261 262rebasing of assemblies 263======================================================= 264Neither assemblies nor policy assemblies may be rebased. This would 265make the signature invalid. Therefore all assemblies must be contained 266in postprocess/rebase/no_rebase.txt 267