Mercurial > p > roundup > code

comparison doc/upgrading.txt @ 6638:e1588ae185dc issue2550923_computed_property

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge from default branch. Fix travis.ci so CI builds don't error out
author John Rouillard <rouilj@ieee.org>
date Thu, 21 Apr 2022 16:54:17 -0400
parents 120b0bb05b6e
children 9ca5cbffa0c4
comparison
equal deleted inserted replaced
6508:85db90cc1705 6638:e1588ae185dc
1 .. meta::
2 :description language=en:
3 Critical documentation on how to upgrade the Roundup Issue
4 Tracker. Actions that must or can be taken when upgrading from
5 one version to another are documented here.
6
1 .. index:: Upgrading 7 .. index:: Upgrading
2 8
3 ====================================== 9 ======================================
4 Upgrading to newer versions of Roundup 10 Upgrading to newer versions of Roundup
5 ====================================== 11 ======================================
27 .. index:: Upgrading; 2.0.0 to 2.1.0 33 .. index:: Upgrading; 2.0.0 to 2.1.0
28 34
29 Migrating from 2.1.0 to 2.x.y 35 Migrating from 2.1.0 to 2.x.y
30 ============================= 36 =============================
31 37
32 Check Compression Settings 38 Rdbms version change from 6 to 7 (required)
33 -------------------------- 39 -------------------------------------------
34 40
35 Read the `administration guide`_ section on 'Configuring Compression'. 41 This release includes two changes that require updates to the database
42 schema:
43
44 1. The size of words included in the Roundup FTS indexers have been
45 increased from 25 to 50. This requires changes to the database
46 columns used by the native indexer. This also affect the whoosh
47 and xapian indexers.
48 2. Some databases that include native full-text search (native-fts
49 indexer) searching are now supported.
50
51 You should run the ``roundup-admin migrate`` command for your
52 tracker once you've installed the latest codebase.
53
54 Do this before you use the web, command-line or mail interface
55 and before any users access the tracker.
56
57 If successful, this command will respond with either "Tracker
58 updated" (if you've not previously run it on an RDBMS backend) or
59 "No migration action required" (if you have run it, or have used
60 another interface to the tracker, or are using anydbm).
61
62 See `below for directions on enabling native-fts`_.
63
64 .. _below for directions on enabling native-fts: \
65 #enhanced-full-text-search-optional
66
67 The increase in indexed word length also affects whoosh and xapian
68 backends. You may want to run ``roundup-admin -i tracker_home
69 reindex`` if you want to index or search for longer words in your full
70 text searches. Re-indexing make take some time.
71
72 Check compression settings (optional)
73 -------------------------------------
74
75 Read the `administration guide`_ section on `Configuring Compression`_.
36 76
37 Upgrade tracker's config.ini file. Use:: 77 Upgrade tracker's config.ini file. Use::
38 78
39 roundup-admin -i /path/to/tracker updateconfig newconfig.ini 79 roundup-admin -i /path/to/tracker updateconfig newconfig.ini
40 80
42 merge any local comments from the tracker's ``config.ini`` into 82 merge any local comments from the tracker's ``config.ini`` into
43 ``newconfig.ini``. Compare the old and new files and configure new 83 ``newconfig.ini``. Compare the old and new files and configure new
44 compression settings as you want. Then replace ``config.ini`` with the 84 compression settings as you want. Then replace ``config.ini`` with the
45 ``newconfig.ini`` file. 85 ``newconfig.ini`` file.
46 86
47 Search Added to User Index Page 87 Search added to user index page (optional)
48 ------------------------------- 88 ------------------------------------------
49 89
50 A search form and count of number of hits has been added to the 90 A search form and count of number of hits has been added to the
51 ``user.index.html`` template page in the classic template. You may 91 ``user.index.html`` template page in the classic template. You may
52 want to merge the search form and footer into your template. 92 want to merge the search form and footer into your template.
53 93
94 Enhanced full-text search (optional)
95 ------------------------------------
96
97 SQLite's `FTS5 full-text search engine`_ is available as is
98 `PostgreSQL's full text search`_. Both require a schema upgrade so you
99 should run::
100
101 roundup-admin -i tracker_home migrate
102
103 to create FTS specific tables before restarting the roundup-web or
104 email interfaces.
105
106 SQLite 3.9.0+ or PostgreSQL 11.0+ are required to use this feature.
107 When using SQLite, all full text search fields will allow searching
108 using the MATCH query format described at:
109 https://www.sqlite.org/fts5.html#full_text_query_syntax. When using
110 PostgreSQL either the websearch_to_tsquery or to_tsquery formats
111 described on
112 https://www.postgresql.org/docs/14/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES
113 can be used. The default is websearch. Prefixing the search with
114 ``ts:`` enables tsquery mode.
115
116 A list of words behaves almost the same as the default text search
117 (`native`). So the search string `fts search` will find all issues
118 that have both of those words (an AND search) in a text-field (like
119 title) or in a message (or file) attached to the issue.
120
121 One thing to note is that native-fts searches do not ignore words
122 longer than 50 characters or less than 2 characters. Also SQLite does
123 not filter out common words (i.e. there is no stopword list). So words
124 like "and", "or", "then", "with" ... are included in the FTS5 search.
125
126 You must explicitly enable this search mechanism by changing the
127 ``indexer`` setting in ``config.ini`` to ``native-fts``. Native-fts
128 must be explicitly chosen. This is different from Xapian or Whoosh
129 indexers, which are chosen if they are installed in the Python
130 environment. This prevents the existing native indexing from being
131 discarded if ``indexer`` is not set.
132
133 Next re-index your data with ``roundup-admin -i tracker_home
134 reindex``. This can take a while depending on the size of the tracker.
135
136 You may want to update your ``config.ini`` by following the directions
137 above to get the latest documentation.
138
139 See the `administration guide notes on native-fts`_ for further details.
140
141 Adding error reporting templates (optional)
142 -------------------------------------------
143
144 Currently some internal errors result in a bare html page with an
145 error message. The usual chrome supplied by page.html is not shown.
146 For example query language syntax errors for full text search methods
147 will display a bare HTML error page.
148
149 If you add an ``_generic.400.html`` template to the html directory, you
150 can display the error inside of the layout provided by the ``page.html``
151 template. This can make fixing the error and navigation easier. You
152 can use the ``_generic.404.html`` template to create a
153 ``_generic.400.html`` by modifying the title and body text. You can test
154 the 400 template by appending ``@template=400`` to the url for the
155 tracker.
156
157 Change passwords using crypt module (optional)
158 ----------------------------------------------
159
160 The crypt module is being removed from the standard library. Any
161 stored password using crypt encoding will fail to verify once the
162 crypt module is removed (expected in Python 3.13 see
163 pep-0594). Automatic migration of passwords (if enabled in config.ini)
164 re-encrypts old passwords using something other than crypt if a user
165 logs in using the web interface.
166
167 You can find users with passwords still encrypted using crypt by
168 running::
169
170 roundup-admin -i <tracker_home> table password,id,username
171
172 Look for lines starting with ``{CRYPT}``. You can reset the user's
173 password using::
174
175 roundup-admin -i <tracker_home>
176 roundup> set user16 password=somenewpassword
177
178 changing ``16`` to the id in the second column of the table output.
179 The example uses interactive mode (indicated by the ``roundup>``
180 prompt). This prevents the new password from showing up in the output
181 of ps or shell history. The new password will be encrypted using the
182 default encryption method (usually pbkdf2).
54 183
55 Migrating from 2.0.0 to 2.1.0 184 Migrating from 2.0.0 to 2.1.0
56 ============================= 185 =============================
57 186
58 Rdbms version change from 5 to 6 (**) 187 Rdbms version change from 5 to 6 (**)
3262 3391
3263 .. _`customisation documentation`: customizing.html 3392 .. _`customisation documentation`: customizing.html
3264 .. _`security documentation`: security.html 3393 .. _`security documentation`: security.html
3265 .. _`administration guide`: admin_guide.html 3394 .. _`administration guide`: admin_guide.html
3266 .. _`xmlrpc guide`: xmlrpc.html 3395 .. _`xmlrpc guide`: xmlrpc.html
3396 .. _FTS5 full-text search engine: https://www.sqlite.org/fts5.html
3397 .. _PostgreSQL's full text search: https://www.postgresql.org/docs/current/textsearch.html
3398 .. _`administration guide notes on native-fts`: admin_guide.html#configuring-native-fts-full-text-search
3399 .. _Configuring Compression: admin_guide.html#configuring-compression
Roundup Issue Tracker: http://roundup-tracker.org/