Mercurial Repository: p/roundup/code: doc/upgrading.txt comparison

comparison doc/upgrading.txt @ 7801:af898d1d66dc

doc: run sphinx-lint over docs. Pointed out mutiple use of `x` where it should be ``x``. Also trailing whitespace and lines that are too long. Replaced all tabs by spaces. Also fixed spelling error while I was there. Fixed broken internal link.

author	John Rouillard <rouilj@ieee.org>
date	Wed, 13 Mar 2024 00:51:09 -0400
parents	8bdf0484215c
children	0fe2b9f6e19f

comparison

equal deleted inserted replaced

-:2d4684e4702d
+:af898d1d66dc
 .. meta::
 :description:
-	Critical documentation for upgrading the Roundup Issue
+Critical documentation for upgrading the Roundup Issue
-	Tracker. Actions that must be taken when upgrading from
+Tracker. Actions that must be taken when upgrading from
-	one version to another are documented here.
+one version to another are documented here.
 .. index:: Upgrading
 ======================================
 Upgrading to newer versions of Roundup
 (user, name, password ...) that are in the tracker's
 ``config.ini`` will override the service settings. So you
 want to leave the ``config.ini`` settings blank. E.G.::
 [rdbms]
 name =
 host =
 port =
 user =
 password =
-service =  roundup_roundup
+service = roundup_roundup
 Setting ``service`` to ``roundup_roundup`` with
 the following in the service file::
 [roundup_roundup]
 PostgreSQL database use a numeric type that
 truncates/rounds expiration timestamps. This results in
 entries being purged early or late (depending on whether
 it rounds up or down). The discrepancy is a couple of
 days for Mysql or a couple of minutes for PostgreSQL.
 Session keys stay for a week or more and CSRF keys are
 two weeks by default. As a result, this isn't usually a
 visible issue. This migration updates the numeric types
 to ones that supports more significant figures.
 Update ``config.ini``'s ``password_pbkdf2_default_rounds`` (required)
 ---------------------------------------------------------------------
 Roundup hashes passwords using PBKDF2 with SHA1. In this release, you
-can `upgrade to PBKDF2-SHA512 from current PBKDF2-SHA1`.  If you
+can `upgrade to PBKDF2-SHA512 from current PBKDF2-SHA1 (recommended)`_.  If you
 upgrade, you want to set the default rounds according to the
 PBKDF2-SHA512 upgrading directions. Note that this algorithm is
 expected to be the default in a future version of Roundup.
 If you don't want to upgrade, we recommend that you increase the
 You can verify that PBKDF2S5 is used by default by running::
 roundup-admin -i <tracker_home> perftest password rounds=250,000
 and verify that the scheme is PBKDF2S5.
 .. _the interfaces.py file:
 reference.html#interfaces-py-hooking-into-the-core-of-roundup
 .. |the interfaces.py file| replace:: the ``interfaces.py`` file
 sqlite3 <tracker_home>/db/db "pragma journal_mode;"
 2. If it returns ``delete``, change it to WAL mode using::
 sqlite3 <tracker_home>/db/db "pragma journal_mode=WAL;"
 3. verify by running the command in step 1 again and you
 should get ``wal``.
 If you are using SQLite for session and otk databases,
 perform the same steps replacing ``db`` with ``db-session``
 Change in processing allowed_api_origins setting (info)
 -------------------------------------------------------
 In this release you can use both ``*`` (as the first origin) and
-explicit origins in the `allowed_api_origins`` setting in
+explicit origins in the ``allowed_api_origins`` setting in
 ``config.ini``. (Before it was only one or the other.)
 You do not need to use ``*``. If you do, it allows any client
 anonymous (unauthenticated) access to the Roundup tracker. This
 is the same as browsing the tracker without logging in. If they
 https://www.postgresql.org/docs/14/textsearch-controls.html#TEXTSEARCH-PARSING-QUERIES
 can be used. The default is websearch. Prefixing the search with
 ``ts:`` enables tsquery mode.
 A list of words behaves almost the same as the default text search
-(`native`). So the search string `fts search` will find all issues
+(``native``). So the search string ``fts search`` will find all issues
 that have both of those words (an AND search) in a text-field (like
 title) or in a message (or file) attached to the issue.
 One thing to note is that native-fts searches do not ignore words
 longer than 50 characters or less than 2 characters. Also SQLite does
 +    from html import escape
 +except ImportError:
 +    from cgi import escape
 try:
-	 import pytz
+import pytz
 @@ -25,7 +28,7 @@
-		 s = ' '
+s = ' '
-		 if zone == value:
+if zone == value:
-		     s = 'selected=selected '
+s = 'selected=selected '
 -            z = cgi.escape(zone)
 +            z = escape(zone)
 See https://issues.roundup-tracker.org/issue2551136 for more details.
 this section.
 Make sure that user can view labelprop on classes (required)
 ------------------------------------------------------------
-If you have View permissions that use ```properties=...```, make sure
+If you have View permissions that use ``properties=...``, make sure
 that the `labelprop <reference.html#setlabelprop-property>`_ for the
 class is listed in the properties list.
 The first one of these that exists must must be in the list:
 # who updated the issue, but it could be useful in some
 # unusual circumstances.
 # If set to some other value, the value is used as the reply-to
 # address. It must be a valid RFC2822 address or people will not be
 # able to reply.
 # Default:
 replyto_address =
 Login from a search or after logout works better (required)
 -----------------------------------------------------------
 The login form has been improved to work with some back end code
 changes. Now when a user logs in they stay on the same page where they
 started the login. To make this work, you must change the tal that is
 used to set the ``__came_from`` form variable. Note that the url
 assigned to __came_from must be url encoded/quoted and be under the
 tracker's base url. If the base_url uses http, you can set the url to
 https.
 Replace the existing code in the tracker's html/page.html page that
 looks similar to (look for name="__came_from"):
 :class: big-code
 <tal:block tal:repeat="qs request/user/queries">
 -    <a href="#" tal:attributes="href string:${qs/klass}?${qs/url}&@dispname=${qs/name}"
 +    <a href="#" tal:attributes="href string:${qs/klass}?${qs/url}&@dispname=${qs/name/url_quote}"
-	  tal:content="qs/name">link</a><br>
+tal:content="qs/name">link</a><br>
 </tal:block>
 Find the tal:repeat line that loops over all queries. Then
 change the value assigned to @dispname in the href attribute from
 ${qs/name} to ${qs/name/url_quote}. Note that you should *not* change
 This should make defining complex permissions much easier. Consider::
 def issue_private_access(db, userid, itemid, **ctx):
 if not db.issue.get(itemid, 'private'):
 # allow access to everything if not private
-	   return True
+return True
-	# It is a private issue hide nosy list
+# It is a private issue hide nosy list
-	# Note that the nosy property *must* be listed
+# Note that the nosy property *must* be listed
-	# in permissions argument to the addPermission
+# in permissions argument to the addPermission
-	# definition otherwise this check command
+# definition otherwise this check command
-	# is not run.
+# is not run.
-	if ctx['property'] == 'nosy':
+if ctx['property'] == 'nosy':
-	   return False # deny access to this property
+return False # deny access to this property
-	# allow access for editing, viewing etc. of the class
+# allow access for editing, viewing etc. of the class
-	return True
+return True
 e = db.security.addPermission(name='Edit', klass='issue',
 check=issue_private_access,
-				  properties=['nosy'],
+properties=['nosy'],
 description="Edit issue checks")
 It is suggested that you change your checks to use the ``**ctx``
 parameter. This is expected to be the preferred form in the future.
 You do not need to use the ``ctx`` parameter in the function if you do

Mercurial > p > roundup > code

comparison doc/upgrading.txt @ 7801:af898d1d66dc