diff --git a/.codecov.yml b/.codecov.yml index e0d835df0..40663c7f5 100644 --- a/.codecov.yml +++ b/.codecov.yml @@ -9,6 +9,5 @@ ignore: - "roundup/cgi/TAL/talgettext.py" # utility command - "roundup/cgi/TAL/DummyEngine.py" # test harness - "roundup/cgi/apache.py" # mod_python is deprecated - - "roundup/install_util.py" # another build utlity - "roundup/dist" # more build utils - "roundup/test" # code used for testing diff --git a/.github/dependabot.yml b/.github/dependabot.yml index fc75e2ae2..79414b360 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -18,6 +18,8 @@ updates: directory: "/" schedule: interval: "weekly" + cooldown: + default-days: 7 # - package-ecosystem: "docker" # directory: "/scripts/Docker" # target-branch: "master" diff --git a/.github/workflows/anchore.yml b/.github/workflows/anchore.yml index a1c2e6a5f..7f62ff8d8 100644 --- a/.github/workflows/anchore.yml +++ b/.github/workflows/anchore.yml @@ -37,22 +37,26 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout the code - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + persist-credentials: false - name: Build the Docker image run: docker pull python:3-alpine; docker build . --file scripts/Docker/Dockerfile --tag localbuild/testimage:latest - name: List the Docker image run: docker image ls - name: Run the Anchore scan action itself with GitHub Advanced Security code scanning integration enabled - uses: anchore/scan-action@c35e932c2a7c572bfdb1c3dbcdadb2d4fc62418d # 3.6.1 + uses: anchore/scan-action@e1165082ffb1fe366ebaf02d8526e7c4989ea9d2 # v7.4.0 id: scan with: image: "localbuild/testimage:latest" fail-build: true - name: Upload Anchore Scan Report if: always() - uses: github/codeql-action/upload-sarif@65c74964a9ed8c44ed9f19d4bbc5757a6a8e9ab9 # v2.16.1 + uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0 with: sarif_file: ${{ steps.scan.outputs.sarif }} - name: Inspect action SARIF report if: always() - run: cat ${{ steps.scan.outputs.sarif }} + run: cat ${STEPS_SCAN_OUTPUTS_SARIF} + env: + STEPS_SCAN_OUTPUTS_SARIF: ${{ steps.scan.outputs.sarif }} diff --git a/.github/workflows/build-xapian.yml b/.github/workflows/build-xapian.yml index 2441a1a8a..318683529 100644 --- a/.github/workflows/build-xapian.yml +++ b/.github/workflows/build-xapian.yml @@ -26,7 +26,7 @@ concurrency: jobs: test: name: build xapian - runs-on: ubuntu-22.04 + runs-on: ubuntu-24.04 env: # get colorized pytest output even without a controlling tty @@ -42,11 +42,13 @@ jobs: # if: {{ false }} # continue running if step fails # continue-on-error: true - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + persist-credentials: false # Setup version of Python to use - name: Set Up Python 3.13 - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0 + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 with: python-version: 3.13 allow-prereleases: true @@ -69,7 +71,7 @@ jobs: # allow remote ssh into the CI container. I need this to debug # some xfail cases - name: Setup tmate session - uses: mxschmitt/action-tmate@v3 + uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3.24 if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }} timeout-minutes: 60 with: @@ -82,7 +84,7 @@ jobs: # Sphinx required to build the xapian python bindings. Use 1.8.5 on # older python and newest on newer. pip install sphinx - XAPIAN_VER="1.4.25"; echo $XAPIAN_VER; + XAPIAN_VER="1.4.22"; echo $XAPIAN_VER; cd /tmp curl -s -O https://oligarchy.co.uk/xapian/$XAPIAN_VER/xapian-bindings-$XAPIAN_VER.tar.xz tar -Jxvf xapian-bindings-$XAPIAN_VER.tar.xz diff --git a/.github/workflows/ci-test.yml b/.github/workflows/ci-test.yml index 0132c1853..bb2962126 100644 --- a/.github/workflows/ci-test.yml +++ b/.github/workflows/ci-test.yml @@ -45,6 +45,12 @@ jobs: if: "!contains(github.event.head_commit.message, 'no-github-ci')" + # run the finalizer for coveralls even if one or more + # experimental matrix runs fail. + # moving it above strategy produces unexpected value false + # moving it below (here) produces unexpected value ''. + continue-on-error: ${{ matrix.experimental }} + strategy: fail-fast: false max-parallel: 4 @@ -52,44 +58,39 @@ jobs: # Run in all these versions of Python python-version: # - "2.7" + - "3.14" + - "3.14t" - "3.13" - # - 3.6 run via include on ubuntu 20.04 - # - "3.7" - - "3.8" - # - "3.9" - - "3.10" - - "3.11" - "3.12" + - "3.10" # use for multiple os or ubuntu versions #os: [ubuntu-latest, macos-latest, windows-latest] - # ubuntu latest 22.04 12/2022 - os: [ubuntu-latest, ubuntu-20.04] + # ubuntu latest 24.04 12/2024 + os: [ubuntu-latest] # if the ones above fail. fail the build experimental: [ false ] include: - # example: if 3.13 fails the jobs still succeeds + # example: if this version fails the jobs still succeeds # allow-prereleases in setup-python allows alpha/beta - # releases to run - #- python-version: 3.13 - # os: ubuntu-22.04 - # experimental: true - - # 3.6 not available on new 22.04 runners, so run on 20.04 ubuntu - - python-version: 3.6 - os: ubuntu-20.04 - - exclude: - # skip all python versions on 20.04 except explicitly included - - os: ubuntu-20.04 - - # run the finalizer for coveralls even if one or more - # experimental matrix runs fail. - # moving it above strategy produces unexpected value false - # moving it below (here) produces unexpected value ''. - # continue-on-error: ${{ matrix.experimental }} + # releases to run. Also allow free threaded python testing + - python-version: 3.15-dev + os: ubuntu-24.04 + experimental: true + - python-version: 3.15t-dev + os: ubuntu-24.04 + experimental: true + + #exclude: + # skip all python versions on explicit 20.04/24.04 unless + # explicitly included + #- os: ubuntu-24.04 + + # disable when testing ubuntu-24.04 to speed up + # runs. + # - os: ubuntu-latest env: # get colorized pytest output even without a controlling tty @@ -105,11 +106,13 @@ jobs: # if: {{ false }} # continue running if step fails # continue-on-error: true - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + persist-credentials: false # Setup version of Python to use - name: Set Up Python ${{ matrix.python-version }} - uses: actions/setup-python@82c7e631bb3cdc910f68e0081d67478d79c6982d # v5.1.0 + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 with: python-version: ${{ matrix.python-version }} allow-prereleases: true @@ -121,23 +124,32 @@ jobs: # Display the Python version being used - name: Display Python and key module versions run: | - python -c "import sys; print('python version: ', sys.version)" + python --version --version + python -c "import sysconfig; print('GIL IS DISABLED: ', sysconfig.get_config_vars().get('Py_GIL_DISABLED', 'not defined'));" python -c "import sqlite3; print('sqlite version: ', sqlite3.sqlite_version)" python -c "import setuptools; print('setuptools version: ', setuptools.__version__);" + # from: + # https://hugovk.dev/blog/2025/free-threaded-python-on-github-actions/ + - name: Set PYTHON_GIL when freethreaded + if: endsWith(matrix.python-version, 't') + run: | + echo "PYTHON_GIL=0" >> "$GITHUB_ENV" - name: Update pip run: python -m pip install --upgrade pip - # note pytest-env is not needed for redis password as there is - # no password on CI's redis. + # note pytest-env is not required for redis password as there is + # no password on CI's redis. But pytest logs a warning if it's + # missing. pytest-subtests isn't needed with + # pytest 9.0.0+, but 9.0 only supports 3.10+ so include for 3.7+. - name: Install pytest and other packages needed for running tests - run: pip install flake8 hypothesis mock pytest pytest-cov requests sphinx-tabs + run: pip install flake8 hypothesis mock pytest pytest-cov pytest-env pytest-subtests requests sphinx-tabs # https://github.com/mxschmitt/action-tmate # allow remote ssh into the CI container. I need this to debug # some xfail cases - name: Setup tmate session - uses: mxschmitt/action-tmate@v3 + uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3.24 if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }} timeout-minutes: 10 with: @@ -206,9 +218,19 @@ jobs: pip install mysqlclient pip install psycopg2 + # https://github.com/mxschmitt/action-tmate + # allow remote ssh into the CI container. I need this to debug + # some xfail cases + - name: Setup tmate session + uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3.24 + if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }} + timeout-minutes: 10 + with: + limit-access-to-actor: true + - name: Install auxiliary packages run: | - sudo apt-get install swig gpgsm libgpgme-dev + sudo apt-get install swig gpg gpgsm libgpgme-dev # pygments for markdown2 to highlight code blocks pip install markdown2 pygments # docutils for ReStructuredText @@ -220,11 +242,15 @@ jobs: run: | set -xv pip install zstd || true + # justhtml supports python 3.10 or newer according to pypi + # page, but will install on 3.8 (and maybe 3.9) but formats + # differently. So skip install if before 3.10. + if echo $PYTHON_VERSION | grep '^3\...'; then + pip install justhtml || true; fi if [[ "$PYTHON_VERSION" != "2."* ]]; then pip install Markdown; fi - name: Install xapian - if: matrix.python-version != '3.13' run: | set -xv sudo apt-get install libxapian-dev @@ -232,11 +258,7 @@ jobs: # older python and newest on newer. if [[ $PYTHON_VERSION == "2."* ]]; then pip install sphinx==1.8.5; fi if [[ $PYTHON_VERSION == '3.'* ]] ; then pip install sphinx; fi - if [[ $PYTHON_VERSION != "3.13" ]]; then - XAPIAN_VER=$(dpkg -l libxapian-dev | tail -n 1 | awk '{print $3}' | cut -d '-' -f 1); echo $XAPIAN_VER; - else - XAPIAN_VER="1.4.25"; echo $XAPIAN_VER; - fi + XAPIAN_VER=$(dpkg -l libxapian-dev | tail -n 1 | awk '{print $3}' | cut -d '-' -f 1); echo $XAPIAN_VER; cd /tmp curl -s -O https://oligarchy.co.uk/xapian/$XAPIAN_VER/xapian-bindings-$XAPIAN_VER.tar.xz tar -Jxvf xapian-bindings-$XAPIAN_VER.tar.xz @@ -259,7 +281,7 @@ jobs: diff -u configure.FCS configure || true; \ ./configure --prefix=$VIRTUAL_ENV --with-python3 --disable-documentation; \ fi - case "$PYTHON_VERSION" in "3.13") echo skipping xapian build;; *) make && sudo make install; esac + make && sudo make install - name: Test build roundup and install locale so lang tests work. run: | @@ -279,11 +301,8 @@ jobs: -W "ignore:'U' mode::docutils.io" \ -W "ignore:unclosed:ResourceWarning:roundup.roundup.demo" \ -W "ignore:unclosed file:ResourceWarning:enum" \ - -v test/ --cov=roundup - if [[ "$PYTHON_VERSION" != "3.6" ]]; then - # coverage before 3.6 doesn't support lcov output + -v test/ --cov=roundup coverage lcov - fi else # python2 case pytest -v -r a --durations=20 test/ --cov=roundup @@ -294,7 +313,7 @@ jobs: - name: Upload coverage to Codecov # see: https://github.com/codecov/codecov-action#usage - uses: codecov/codecov-action@4fe8c5f003fae66aa5ebb77cfd3e7bfbbda0b6b0 # v3.1.5 + uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0 with: verbose: true token: ${{ secrets.CODECOV_TOKEN }} @@ -302,7 +321,7 @@ jobs: - name: Upload coverage to Coveralls # python 2.7 and 3.6 versions of coverage can't produce lcov files. if: matrix.python-version != '2.7' && matrix.python-version != '3.6' - uses: coverallsapp/github-action@3dfc5567390f6fa9267c0ee9c251e4c8c3f18949 # v2.2.3 + uses: coverallsapp/github-action@5cbfd81b66ca5d10c19b062c04de0199c215fb6e # v2.3.7 with: github-token: ${{ secrets.GITHUB_TOKEN }} path-to-lcov: coverage.lcov @@ -338,7 +357,7 @@ jobs: steps: - name: Coveralls Finished - uses: coverallsapp/github-action@3dfc5567390f6fa9267c0ee9c251e4c8c3f18949 # v2.2.3 + uses: coverallsapp/github-action@5cbfd81b66ca5d10c19b062c04de0199c215fb6e # v2.3.7 with: github-token: ${{ secrets.github_token }} parallel-finished: true diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml index 321f5d54f..918184dc3 100644 --- a/.github/workflows/codeql-analysis.yml +++ b/.github/workflows/codeql-analysis.yml @@ -49,11 +49,13 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + persist-credentials: false # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL - uses: github/codeql-action/init@65c74964a9ed8c44ed9f19d4bbc5757a6a8e9ab9 # v2.16.1 + uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0 with: languages: ${{ matrix.language }} # If you wish to specify custom queries, you can do so here or in a config file. @@ -64,7 +66,7 @@ jobs: # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). # If this step fails, then you should remove it and run the build manually (see below) - name: Autobuild - uses: github/codeql-action/autobuild@65c74964a9ed8c44ed9f19d4bbc5757a6a8e9ab9 # v2.16.1 + uses: github/codeql-action/autobuild@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0 # ℹ️ Command-line programs to run using the OS shell. # 📚 https://git.io/JvXDl @@ -78,4 +80,4 @@ jobs: # make release - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@65c74964a9ed8c44ed9f19d4bbc5757a6a8e9ab9 # v2.16.1 + uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0 diff --git a/.github/workflows/ossf-scorecard.yml b/.github/workflows/ossf-scorecard.yml index a5bca1faf..fcd4b7926 100644 --- a/.github/workflows/ossf-scorecard.yml +++ b/.github/workflows/ossf-scorecard.yml @@ -35,12 +35,12 @@ jobs: steps: - name: "Checkout code" - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: persist-credentials: false - name: "Run analysis" - uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 # v2.3.10 + uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3 with: results_file: results.sarif results_format: sarif @@ -62,7 +62,7 @@ jobs: # Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF # format to the repository Actions tab. - name: "Upload artifact" - uses: actions/upload-artifact@26f96dfa697d77e81fd5907df203aa23a56210a8 # v4.3.0 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: SARIF file path: results.sarif @@ -70,6 +70,6 @@ jobs: # Upload the results to GitHub's code scanning dashboard. - name: "Upload to code-scanning" - uses: github/codeql-action/upload-sarif@65c74964a9ed8c44ed9f19d4bbc5757a6a8e9ab9 # v2.16.1 + uses: github/codeql-action/upload-sarif@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0 with: sarif_file: results.sarif diff --git a/.github/workflows/zizmor.yml b/.github/workflows/zizmor.yml new file mode 100644 index 000000000..0c05bf6b0 --- /dev/null +++ b/.github/workflows/zizmor.yml @@ -0,0 +1,23 @@ +name: GitHub Actions Security Analysis with zizmor + +on: + push: + branches: ["main"] + pull_request: + branches: ["**"] + +permissions: {} + +jobs: + zizmor: + runs-on: ubuntu-latest + permissions: + security-events: write + steps: + - name: Checkout repository + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 + with: + persist-credentials: false + + - name: Run zizmor + uses: zizmorcore/zizmor-action@192e21d79ab29983730a13d1382995c2307fbcaa # v0.5.7 diff --git a/.hgignore b/.hgignore index 75ef4674b..5f09b9db2 100644 --- a/.hgignore +++ b/.hgignore @@ -47,3 +47,4 @@ website/www/COPYING.txt website/www/docs website/www/html/ .pytest_cache +.hypothesis diff --git a/.hgtags b/.hgtags index 75c9cd063..4a5f11fac 100644 --- a/.hgtags +++ b/.hgtags @@ -154,3 +154,7 @@ a377590eba34724c5d30d80692257e5ae68aab13 2.4.0b0 0000000000000000000000000000000000000000 2.4.1b1 c10df5dfed95dc37e8092861886bf66614b77062 2.4.0b1 4dfc07ee489ad000c8ffe7ee97b506c94fae6774 2.4.0 +3bf6ad421347c87ae3a6bebe288f8f1dfa7bd6ba 2.5.0b1 +c7a2e01793cdb5228d44df085e3b2f8a73e51c28 2.5.0 +174e6163e178598edd2c33c8c051aa03bd3dbf04 2.6.0b1 +d7abd2cf2be584e4869770dfc616c31d249d8b9e 2.6.0 diff --git a/.travis.yml b/.travis.yml index 018e399bb..a51097b6a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -132,6 +132,7 @@ install: - pip install redis - pip install pytz whoosh pyjwt requests - pip install jinja2 + - pip install psycopg2 # note pytest-env is not needed for redis password as there is # no password on CI's redis. - pip install pytest-cov diff --git a/CHANGES.txt b/CHANGES.txt index c07a86f6f..833178217 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -6,17 +6,181 @@ and template changes not listed here. Each entry has the developer who committed the change in brackets. Many entries without name were done by Richard Jones. -**IMPORTANT** The v1.5.x releases of Roundup were the last to support -Python v2.5 and v2.6. Starting with the v1.6 releases of Roundup -v2.7.2 or later are required to run newer releases of Roundup. -Roundup 2.0 supports Python 3.4 and later. Roundup 2.1.0 supports -python 3.6 or newer (3.4/3.5 might work, but they are not tested). -Roundup 2.4.0 is the last release to support Python 2. +**IMPORTANT** Roundup 2.6 supports Python 3.10 or newer. +Roundup 2.4.0 was the last release to support Python 2. -2025-XX-XX 2.5.0 +2026-07-13 2.6.0 Fixed: +- performance improvement to session_dbm.py:clean(). Also add warning + log message if clean takes longer than 3 seconds. (John Rouillard) +- move RateLimitExceeded exception from roundup.exceptions to + roundup.cgi.exceptions. Also it now inherits from HTTPException + rather than Exception since it is an HTTP exception. (John + Rouillard) +- cleaned up repo. Close obsolete branches and close a split head due + to an identical merge in two different working copies. (John + Rouillard) +- in roundup-admin, using 'pragma history_length interactively now + sets readline history length. Using -P history_length=10 on the + command line always worked. (John Rouillard) +- enhanced error reporting for errors in ini style logging + configuration. (John Rouillard) +- fix bogus javascript emitted by user_src_input macro. (John + Rouillard) +- replaced hostname localhost with 127.0.0.1 in docker healthcheck + script. Found/patch by Norbert Schlemmer. (John Rouillard) +- change some internal classes to use __slots__ for hopefully a small + performance improvement. (John Rouillard) +- issue2551413 - Broken MultiLink columns in CSV export. CSV export of + a multilink link "messages" that does not have a 'name' property + causes a crash. (found/fix by cmeerw; commit and better handling of + non-labeled multilink by John Rouillard) +- in cgi/client.py, set self.language attribute when translator passed + into Client(). (John Rouillard) +- issue2551393 - Named searches lose their name in title when next + page is selected. (John Rouillard) +- code cleanup replace bare except: with except Exception:. (patch by + Sense_wang (haosenwang1018) applied by John Rouillard) +- handle "null" values in json objects sent to a rest endpoint by + filtering them from the object before processing. A "null" value + will not unset an attribute. The 'remove' action using the + PATCH verb can unset the value. Before this change "null" values + retrieved from the REST interface would cause errors when sent + using POST or PUT verbs. Also guard against password being set to + None. (John Rouillard) +- change the html templates so that the password is not required if + the ``login_empty_passwords`` setting is enabled in ``config.ini``. + Directions for your tracker are in upgrading.txt. (John Rouillard) +- fix traceback displayed when roundup-admin install was used with + invalid settings for config.ini. It now reports the error and + provides the usage output. Also usage output starts with a newline + to provide a blank line between the command and the output to + improve readability. (John Rouillard) +- fix bug in 2.5.0 where roundup-admin import (or importtable) fails + to properly set the next available id for the class. (John Rouillard + broke it and fixed it 8-)) +- refactor mime detection/handling in the rest interface. Better + supports some mime types, ads default mime type for files without a + mime type (e.g. message contents). Cleaner code. (John Rouillard) +- run hexora and mitigate/fix some medium sev and above. (John Rouillard) +- Return 400 if environment or header variables + have values with characters outside of the printable ascii range + (32-127). Applies to roundup-server and roundup-cgi. wsgi and Zope + depend on the hosting server for sanitizing. Se waitress wsgi server + bug: + https://github.com/Pylons/waitress/security/advisories/GHSA-m5ff-3wj3-8ph4 + (John Rouillard) +- Cleanups/minor enhancements to roundup.cgi script. (John Rouillard) +- fix back_anydm::Class::get() method to properly return default value + if requested property is set to None. This should fix missing text + indexing for the anydbm backend. (John Rouillard) +- ruff driven cleanups/refactor of indexer* files. (John Rouillard) +- remove ``roundup.anypy.scandir_`` which was needed for python 2 support. + (John Rouillard) +- roundup-server no longer logs connection aborted when a client + disconnects and is using HTTP 1.1 or newer. (John Rouillard) +- replace isinstance(..., type(X)) where X is an instance of a type + (1, {}, [], '', u"") with the type itself (int, dict, list, str, + str). This is a leftover construct from early Python 2. Replacing + them speeds up code (e.g. type({}) vs dict). (John Rouillard) +- issue2551405 - Missing locale .mo files create 500 error on uwsgi + without further info. Added more specific ConnectionAbortedError + and changed IOError handling. Case in issue now logs the exception + for diagnosis. (Reported by Ralf Schlatterbeck; John Rouillard) +- Make queries selected from query edit screen include the query + name/display name. This makes it work the same as invoking a query + from the main "Your Queries" menu. (John Rouillard) +- Fix SearchAction to not clobber a saved search when a new search of + the same name is created. Assume a search named "asearch" + exists. Create a new search (not editing the existing + "asearch"). Set new query params and name it "asearch". Roundup will + warn you that "asearch" already exists and you need to choose a new + name. In the warning form, you rename it to "bsearch" and + save/execute. Before this would overwrite "asearch" as it set the + "@old-queryname" of the warning form to "asearch". So it looked like + you were trying to edit the existing query. This fix modifies the + queryname before generating the error form. So when submitted it + doesn't overwrite "asearch". (John Rouillard) +- update the classic tracker's page.html to remove table based + layout. It now uses html5 landmarks like header, main, search, + nav. It also uses flexbox and grid layouts and includes a viewport + meta tag for use on mobile devices. It can be navigated with the + keyboard. Parts of the page that are too wide for the viewport can + be scrolled horizontally with the keyboard or touch. Some other CSS + changes make it easier to use. This is a first step to making the + classic template more responsive. (John Rouillard) +- jinja2 template dependencies updated: bootstrap 4.4.1 -> 4.6.2. + (John Rouillard) +- issue2551377 - Disabled submit button UI issues. When the submit + button is clicked (triggering submit_once) but client side + validation blocks the submission, the submit button no longer + submits the form. Clicking it says the form has been submitted + please wait. This change allows the submit button to submit the form + again after 5 seconds. (John Rouillard) +- Fix developers.txt doc bug (discovered by Ross Boylan, change by + John Rouillard) +- Handle ConfigurationErrors in demo.py cleanly. Used to dump a full + traceback. Now prints error and exits. (John Rouillard) +- Do not display journal/history fields when user does not have access + to the property being changed. (John Rouillard) +- Fix missing CSRF protection for PATCH method (John Rouillard) + +Features: + +- add support for authorized changes. User can be prompted to enter + their password to authorize a change. If the user's password is + properly entered, the change is committed. (John Rouillard) +- add support for dictConfig style logging configuration. Ini/File + style configs will still be supported. (John Rouillard) +- add 'q' as alias for quit in roundup-admin interactive mode. (John + Rouillard) +- add readline command to roundup-admin to list history, control input + mode etc. Also support bang (!) commands to rerun commands in history + or put them in the input buffer for editing. (John Rouillard) +- add format to logging section in config.ini. Used to set default + logging format. (John Rouillard) +- the default logging format template includes an identifier unique + for a request. This identifier (trace_id) can be use to identify + logs for a specific transaction. Will use nanoid if installed, uses + uuid.uuid4 otherwise. Logging also supports a trace_reason log token + with the url for a web request. The logging format can be changed in + config.ini. (John Rouillard) +- issue2551152 - added basic PGP setup/use info to admin_guide. (John + Rouillard) +- add support for the 'justhtml' html 5 parser library for python >= + 3.10. It is written in pure Python. Used to convert html emails into + plain text. Faster then beautifulsoup4 and it passes the html 5 + standard browser test suite. Beautifulsoup is still supported. (John + Rouillard) +- add a new detector: immutable_file_contents.py that prevents + changes to file contents. By default, the permissions assigned + to FileClass based classes (files, msgs) do not prevent editing + of file contents. While the usual HTML templates don't provide + a way to modify files, the REST interface allows changing file + contents without an audit trail. Manually driving the HTML + interface (via curl for example) also allows content + changes. The new detector prevents changes to file contents via + Roundup even by a user with admin rights. (John Rouillard) +- Added documentation on doing an in place database migration. This is + faster for large databases. (John Rouillard) +- Added installation.txt docs on setting up SCGI support with the + althttpd web server. (John Rouillard) +- add support for tokenless/nonceless CSRF prevention following + https://words.filippo.io/csrf/. (John Rouillard) +- standardize use of ``roundup.anypy.urllib_``. Replace urlparse() with + urlsplit() (recommended) for some speedup. (John Rouillard) +- issue2551368 - version 2.0.0 of the pgp module was published by + Bernhard Reiter. Updated documentation and tests. (Bernhard Reiter, + John Rouillard) + +2025-07-13 2.5.0 + +Fixed: + +- XSS issue in devel and responsive templates. Reported by 4bug of + ChaMd5 Security Team H1 Group. (John Rouillard). - issue2551343 - Remove support for PySQLite. It is unmaintained and sqlite3 is used which is the default for a Python distribution. (John Rouillard) @@ -26,6 +190,78 @@ Fixed: - issue2551131 - Return accept-patch if patch body not accepted (415 code). Accept-Patch returned with acceptable values. (John Rouillard) +- issue2551074 - In "responsive" template: click on hide comment leads + to a red error msg. (Report by Ludwig Reiter; fix John Rouillard) +- issue2550698 - added documentation on filtering using RPN property + expressions. (John Rouillard) +- issue2551372 - Better document necessary headers for REST and fix + logging to log missing Origin header (Ralf Schlatterbeck with + suggestions on documentation by John Rouillard) +- issue2551289 - Invalid REST Accept header with post/put performs + change before returning 406. Error before making any changes to the + db if we can't respond with requested format. (John Rouillard) +- issue2551356 - Add etag header when If-Modified-Since GET request + returns not-modified (304). Breaking change to function signature + for client.py-Client::_serve_file(). (John Rouillard) +- issue2551381 - roundup-server parses URI's with multiple '?" + incorrectly. (John Rouillard) +- issue2551382 - invalid @verbose, @page_* values in rest uri's + generate 409 not 400 error. (John Rouillard) +- fix issues with rest doc and use of PUT on a property item. Response + is similar to use of PUT on the item, not a GET on the + item. Discovered while fuzz testing. (John Rouillard) +- issue2551383 - Setting same address via REST PUT command results in + an error. Now the userauditor does not trigger an error if a user + sets the primary address to the existing value. (John Rouillard) +- issue2551253 - Modify password PBKDF2 method to use SHA512. The + default password hashing algorithm has been upgraded to + PBKDF2-SHA512 from PBKDF2-SHA1. The default pbkdf2 rounds in the + config file has been changed to 250000. The admin should change it + manually if it is at 2 million. PBKDF2-SHA512 (PBKDF2S5) has been + available since release 2.3, but it required a manual step to make + it the default. (John Rouillard) +- fixed a crash with roundup-admin perftest password when rounds not set + on command line. (John Rouillard) +- issue2551374 - Add error handling for filter expressions. Filter + expression errors are now reported. (John Rouillard) +- issue2551384: Modify flow in client.py's REST handler to verify + authorization earlier. The validation order for REST requests + has been changed. Checking user authorization to use the REST + interface is done before validating the Origin header. As a + result, incorrectly formatted CORS preflight requests + (e.g. missing Origin header) can now return HTTP status 403 as + well as status 400. (John Rouillard) +- issue2551387 - TypeError: not indexable. Fix crash due to + uninitialized list element on a (Mini)FieldStorage when unexpected + input is posted via wsgi. (Reported and debugged by Christof + Meerwald; fix John Rouillard) +- close http socket and send a 408 status when a timeout exception + is handed in roundup-server. This prevents another exception + caused by using a timed out socket. (John Rouillard) +- issue2551391, partial fix for issue1513369. input fields were + not getting id's assigned. Fixed automatic id assignment to + input fields. Thinko in the code. (John Rouillard) +- issue1895197 - translated help texts in admin.py not displayed + correctly. (Initial patch tobias-herp, John Rouillard) +- issue2551238 - roundup-server should exit with error if -d + is used without -l . Added code to report + the issue. Added issue with relative paths for log file whn + using -L and -d with roundup-server. (John Rouillard) +- Allow the specification of a "form" parameter for Date fields to make + the popup calendar work when the enclosing form has a name different + from "itemSynopsis". (Ralf Schlatterbeck) +- issue2551376: Fix tracebacks in item templates (Ralf Schlatterbeck) +- issue2551396: Use of os.path.stat.ST_MTIME in python 3.13 crashes + roundup on windows. Replaced with equivalent stat.ST_MTIME. (Randy + on IRC, fix: John Rouillard and R. David Murray (bitdancer)) +- issue2551323: remove functions used for XHTML template + support. XHTML was deprecated in Roundup 2.3.0 and an invalid value + in 2.4.0. (John Rouillard) +- issue2551406: 'Templating Error: too many values to unpack' crash + fixed. (reported by and patch Christof Meerwald, commit/test John + Rouillard) +- fix potential HTTP Response Splitting issue in + roundup-server. Discovered by CodeQL in CI. (John Rouillard) Features: @@ -36,7 +272,54 @@ Features: Marcus Priesch, cleanup to remove python 2 issues, John Rouillard.) - issue2551315 - Document use of RestfulInstance.max_response_row_size to limit data returned - from rest request. + from rest request. (John Rouillard) +- issue2551330 - Add an optional 'filter' function to the Permission + objects and the addPermission method. This is used to optimize search + performance by not checking items returned from a database query + one-by-one (using the check function) but instead offload the + permission checks to the database. For SQL backends this performs the + filtering in the database. (Ralf Schlatterbeck) +- issue2551370 - mark roundup session cookie with __Secure- + prefix. (John Rouillard) +- add -P flag to roundup-server to log client address from + X-Forwarded-For reverse proxy header rather than connecting + address. This logs the actual client address when + roundup-server is run behind a reverse proxy. It also appends a + + sign to the logged address/name. (John Rouillard) +- issue2551068 - Provide way to retrieve file/msg data via rest + endpoint. Raw file/msg data can be retrieved using the + /binary_content attribute and an Accept header to select the mime + type for the data (e.g. image/png for a png file). The existing html + interface method still works and is supported, but is legacy. (John + Rouillard) +- added fuzz testing for some code. Found issue2551382 and + others. (John Rouillard) +- issue2551116 - Replace xmlrpclib (xmlrpc.client) with defusedxml. + Added support for defusedxml to better secure the xmlrpc + endpoint. (John Rouillard) +- Added new instance.registerUtilMethod() method to make using complex + templating easier as it provides a default Client instance to the + templating method. (John Rouillard) +- Added new templating utils.set_http_response(integer) method to + allow reporting an error to the user from a template. (John + Rouillard) +- issue2551390 - Replace text input/calendar popup with native + date input. Also add double-click and exit keyboard handlers to + allow copy/paste/editing the text version of the date. Configurable + via the use_browser_date_input setting in the [web] section of + config.ini. By default browser native dates are turned off. + (John Rouillard, Ralf Schlatterbeck) +- Use native number type input for Number() and Integer() + properties. Integer() uses step=1 as well. Configurable via the + use_browser_number_input setting in the [web] section of config.ini. + Set off by default. See + https://issues.roundup-tracker.org/issue2551398 for discussion of + issues with native number inputs. (John Rouillard, Ralf + Schlatterbeck) +- issue2551231 - template.py-HTMLClass::classhelp doesn't merge + user defined classes. It now merges them in. (John Rouillard) +- re-enable support for GPG/PGP encrypted emails using new python gpg + package on the test pypi instance. (Paul Schwabauer) 2024-07-13 2.4.0 diff --git a/COPYING.txt b/COPYING.txt index ac8764339..5df83e10a 100644 --- a/COPYING.txt +++ b/COPYING.txt @@ -1,11 +1,12 @@ -Roundup, exclusive of the Zope page templates, is `MIT licensed`_. +Roundup, exclusive of the Zope page templates and vendored cgi.py, is +`MIT licensed`_. .. _MIT licensed: https://opensource.org/license/mit Roundup Licensing ----------------- -| Copyright (c) 2009-2024 Roundup-Team (https://opensource.org/license/mit) +| Copyright (c) 2009-2026 Roundup-Team (https://opensource.org/license/mit) | Copyright (c) 2003-2009 Richard Jones (richard@mechanicalcat.net) | Copyright (c) 2002 eKit.com Inc | Copyright (c) 2001 Bizar Software Pty Ltd @@ -117,8 +118,12 @@ Note link for http://www.zope.com/Marks is dead. Vendored cgi.py module ---------------------- -This module is licensed under the Python Software Foundation License -Version 2 as it was extracted from the 3.12 Python distribution. +This module is licensed under the `Python Software Foundation License +Version 2`_ as it was extracted from the 3.12 Python distribution. + +.. _Python Software Foundation License Version 2: + https://opensource.org/license/Python-2.0 + PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 -------------------------------------------- diff --git a/RELEASE.txt b/RELEASE.txt index 1b1a4b173..4cfedf93f 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -24,10 +24,9 @@ Roundup release checklist: 2. Run unit tests! They should pass successfully. Install pytest using pip2/pip3 for python2 and python3. Then invoke pytest - using both python versions from the top of the roundup tree: + using both python versions from the top of the roundup tree python3 -m pytest test/ - python2 -m pytest test/ 3. Update version in: CHANGES.txt (set date for version as well) @@ -39,7 +38,7 @@ Roundup release checklist: org.opencontainers.image.version 3a. Update license end date in COPYING.txt 3b. Update doc/acknowledgements.txt (add section for - release, churn contributers etc.). (Use hg churn -c -r ####..####) + release, churn contributers etc.). (Use hg churn -c -r 2.5.0..default) 4. Update documentation doc/announcement.txt @@ -72,13 +71,7 @@ Roundup release checklist: python3 setup.py check --restructuredtext --metadata --strict -6. Clean out all *.orig, *.rej, .#* files from the source. - - find . -name '*.orig' -exec rm {} \; - find . -name '*.rej' -exec rm {} \; - find . -name '.#*' -exec rm {} \; - -6a. Rebuild .mo translation files in distribution +6. Rebuild .mo translation files in distribution cd locale make @@ -89,7 +82,15 @@ Roundup release checklist: python3 setup.py clean --all rm -rf build/share # deletes locale .mo files - Build including new .mo files built in 6a. + Clean out all *.orig, *.rej, .#* files from the source. + + find . -name '*.orig' -exec rm {} \; + find . -name '*.rej' -exec rm {} \; + find . -name '.#*' -exec rm {} \; + +7a. + + Build including new .mo files built in 6. python3 setup.py build @@ -97,7 +98,16 @@ Roundup release checklist: 8. Rebuild documentation in "share/doc/roundup/html" - python3 setup.py build_doc + cd doc + make + cd .. + + runs commands to turn man pages into html files and adds them to + html_extra/man_pages subdir. Then it generates html text from + running roundup_admin. Then it generates a current copy of a + config.ini file. Then it runs: + + python3 setup.py build_doc 9. Generate source distribution: @@ -105,10 +115,11 @@ Roundup release checklist: (if you find sdist a little verbose, add "--quiet" to the end of the command) + 9a. 2021/04/17 skip this for now. Need to make sure that whl installs executable scripts properly and update these directions to test. - python2 setup.py bdist_wheel; python3 setup.py bdist_wheel + python3 setup.py bdist_wheel to create binary distributions in wheel format. (egg format is deprecated.) @@ -118,7 +129,7 @@ Roundup release checklist: added and removed files. Last release e.g. 1.5.1 where tip is what would become 1.6) E.G. - hg status --rev 2.2.0:tip | sed -ne 's/^A //p' | while read i ; \ + hg status --rev 2.5.0:default | sed -ne 's/^A //p' | while read i ; \ do echo $i; grep "$i" roundup.egg-info/SOURCES.txt; done | \ uniq -c | sort -rn @@ -129,20 +140,21 @@ Roundup release checklist: (Note: files under website/ shouldn't be in the manifest.) 10a: Check for removed files still in manifest: - hg status --rev 2.2.0:tip | sed -ne 's/^R //p' | while read i ; \ + hg status --rev 2.5.0:default | sed -ne 's/^R //p' | while read i ; \ do echo $i; grep "$i" roundup.egg-info/SOURCES.txt; done | \ uniq -c | sort -n any file with a count of 2 or more needs to be removed from MANIFEST.in and possibly cleaned out of the build tree. + 10b: if you added/removed files rebuild starting at step 6a. 11. Unpack the new tarball created in dist/roundup-.tar.gz file in /tmp then - a) run tests using installed pytest run under python2 and - python3. (python2 -m pytest test/; python3 -m pytest test/) + a) run tests using installed pytest run under + python3. (python3 -m pytest test/) b) demo.py - with all available Python versions. + with all available Python 3 versions. 11a. (TBD how to test wheel binary distribution before uploading.) 11b. Generate GPG signature file @@ -154,10 +166,10 @@ Roundup release checklist: can add --local=roundup-devel@lists.sourceforge.net. This will create a file by the name .tar.gz.asc. - Move file to website/www/signature directory + Move file to website/www/signatures directory mv .tar.gz.asc ../website/www/signatures/. - hg add ../website/www/signature/.tar.gz.asc + hg add ../website/www/signatures/.tar.gz.asc # commiting the file will be done in step 12 cd .. @@ -237,10 +249,10 @@ Roundup release checklist: the latest -N release. Also roundup:latest points to the newest -N for the newest roundup version.) - docker build -t rounduptracker/roundup:2.4.0 \ + docker build -t rounduptracker/roundup:2.6.0 \ --build-arg="source=pypi" -f scripts/Docker/Dockerfile . - to create the docker image. *Change 2.4.0 to current version* + to create the docker image. *Change 2.6.0 to current version* Always use the exact release tag. 17c. vulnerability scan local image using: @@ -261,18 +273,32 @@ Roundup release checklist: You may need to explicitly update/refresh the scanners with: "docker pull anchore/grype:latest" and similarly for aquasec/trivy if used. + + Note that some security issues may show up. If they are in the + underlying OS package we can't do anything but make sure the + latest python:3-alpine package is used to build the image. Look + at the index digest on the image release page and compare it to + the sha256 at the top of the Dockerfile. + 17d. test roundup in demo mode: docker run -it --rm -p 8917:8080 \ -v $PWD/tracker:/usr/src/app/tracker \ rounduptracker/roundup:2.4.0 demo + FIXME: right now the external port number (8917) in the above + command is hardcoded in DOCKER. It can be overridden usng + PORT_8080=9017 for example. However the host is always + localhost. Consider replacing PORT_8080 with ORIGIN="host:port" + or ORIGIN="port" so that the web URL can be made correct when + running docker on a remote server. + 17e. push to DockerHub login (login using 'docker login ' first and user must be member of rounduptracker org with ability to publish). Replace -N with the release number (e.g. -1, -2, -3...) - docker tag rounduptracker/roundup:2.4.0 roundup-tracker/roundup:latest - docker tag rounduptracker/roundup:2.4.0 roundup-tracker/roundup:2.4.0-N + docker tag rounduptracker/roundup:2.4.0 rounduptracker/roundup:latest + docker tag rounduptracker/roundup:2.4.0 rounduptracker/roundup:2.4.0-N docker push rounduptracker/roundup:2.4.0 docker push rounduptracker/roundup:2.4.0-N docker push rounduptracker/roundup # update roundup:latest diff --git a/demo.py b/demo.py index 861b504e3..13aba73e2 100755 --- a/demo.py +++ b/demo.py @@ -1,6 +1,5 @@ #!/usr/bin/env python3 import sys -import roundup from roundup.demo import main diff --git a/detectors/README.txt b/detectors/README.txt index fde325dd6..508299ce4 100644 --- a/detectors/README.txt +++ b/detectors/README.txt @@ -19,6 +19,10 @@ creator_resolution.py - only allow the creator of the issue to resolve it emailauditor.py - Rename .eml files (from email multi-part bodies) to .mht so they can be downloaded/viewed in Internet Explorer. +immutable_file_contents.py - prevent changes to the contents property + of file and msg classes including by + people with the admin role. + irker.py - communicate with irkerd to allow roundtup to send announcements to an IRC channel. diff --git a/detectors/immutable_file_contents.py b/detectors/immutable_file_contents.py new file mode 100644 index 000000000..d5a8dc391 --- /dev/null +++ b/detectors/immutable_file_contents.py @@ -0,0 +1,22 @@ +# HTML pages don't provide a way to change the contents of a file. +# However REST does allow setting content and the HTML interface can +# be directed to update the content as well. This detector +# prevents changes to file content. + +from roundup.exceptions import UsageError + +def immutable_file_contents(db, cl, nodeid, newvalues): + ''' Prevent content changes to a file + ''' + if 'content' in newvalues: + raise UsageError("File contents are immutable. " + "Rejecting change to contents.") + + +def init(db): + """If you have other FileClass based classes add them here.""" + + # fire before changes are made + db.file.audit('set', immutable_file_contents) + db.msg.audit('set', immutable_file_contents) + diff --git a/detectors/irker.py b/detectors/irker.py index 57ce2bfb1..1d5b45673 100644 --- a/detectors/irker.py +++ b/detectors/irker.py @@ -1,6 +1,6 @@ # This detector sends notification on IRC through an irker daemon -# (http://www.catb.org/esr/irker/) when issues are created or messages -# are added. +# (https://gitlab.com/esr/irker formerly http://www.catb.org/esr/irker/) +# when issues are created or messages are added. # # Written by Ezio Melotti # @@ -14,7 +14,6 @@ # channels = irc://chat.freenode.net/channelname # -from __future__ import print_function import re import json import socket diff --git a/doc/CVE.txt b/doc/CVE.txt index ef4a9abae..f7dc08fcd 100644 --- a/doc/CVE.txt +++ b/doc/CVE.txt @@ -1,29 +1,34 @@ -.. comments: +.. comment: This file is a temporary way to post CVE notifications before a release. - Document the CVE fix info in upgrading.txt. We extract the sections + Document the CVE fix info in upgrading.txt. Extract the sections from upgrading.txt that deal with the CVE into a separate CVE.html. An updated docs/security.html and docs/CVE.html provide the details - on a between release CVE announcment. + on a between release CVE announcment. These file get installed on + the website. - Publishing upgrading.txt would include info on the to be released - roundup software and wouldn't match the rest of the release docs. + We can't publish upgrading.txt as it includes info on the to be + released roundup software and wouldn't match the rest of the + release docs. - To extract the info from upgrading.txt to use in CVE.html, add a - commented out a reference anchor in upgrading.txt. Then in CVE.txt - we use an include directive with start-after and end-before options - to exract the sections from upgrading.txt into CVE.html. + Extract the info from upgrading.txt into CVE.html, by adding a + commented out a reference anchor in upgrading.txt. In CVE.txt we + use an include directive with start-after and end-before options to + extract the section from upgrading.txt into CVE.html. Note a + subheading should be placed right after start-after reference + anchor so that there is an entry in the CVE table of contents. The extracted section in CVE.txt gets the same anchor that is in - upgrading.txt, but is is not commented out. This allows us to swap - out CVE.txt and uncomment the reference in upgrading.txt. Then - rerunning sphinx-build will make security.html point to the sections - in upgrading.html. + upgrading.txt, but is is not commented out. This anchor is used in + security.txt when listing all the CVE's. We can swap out CVE.txt + and uncomment the reference in upgrading.txt when the new release + comes out. Running sphinx-build will make security.html point to + the sections in upgrading.html. For example, in upgrading.txt add a - .. comment: _CVE-2024-39124: + .. comment: _CVE-2024-39124L: before the section for the CVE (use the real CVE number). At the end of the CVE section add an end comment: @@ -34,18 +39,19 @@ security.txt references look like: * `CVE-2024-39124`_ - :ref:`classhelpers (_generic.help.html) are - vulnerable to an XSS attack. ` Requires fixing + vulnerable to an XSS attack. ` Requires fixing tracker homes. - where is the reference. The same reference anchor - is present (commented out) in upgrading.txt. In CVE.txt you - replicate the existing anchor and include to extract the content - section from upgrading.txt. E.G. + where is the reference to local documentation + while ``CVE-2024-39124_`` is the reference to the CVE page. The + same reference anchor is present (commented out) in + upgrading.txt. In CVE.txt you replicate the existing anchor and + include to extract the content section from upgrading.txt. E.G. - .. _CVE-2024-39124: + .. _CVE-2024-39124L: .. include:: upgrading.txt - :start-after: .. comment: _CVE-2024-39124: + :start-after: .. comment: _CVE-2024-39124L: :end-before: .. comment: end of CVE After building the docs, install docs/security.html and @@ -55,18 +61,24 @@ in the CVE announcement from Mitre. + If Mitre is taking too long to give a number, use something like: + + .. _CVE-2024-perm_brokenL + + or similar until Mitre gives a number. + When the release is ready, replace 'comment: _CVE' with '_CVE' in upgrading.txt. This makes the anchors in upgrading.txt live. - Then disable CVE.txt by removing CVE.txt from contents.txt in the - toctree hidden section. Also add docs/CVE.txt to exclude_patterns in - conf.py. + Then comment out the '_CVE' directives in CVE.txt. This will + generate an empty placeholder CVE.txt, but that's ok. No change needs to happen to security.txt as it's using a :ref: and we just changed the location for the ref so sphinx will get the links correct. - Now build the docs and publish to the web site. + Now build the docs and publish (including the rebuilt + security.html) to the web site. =========== Roundup CVE @@ -80,10 +92,36 @@ upgrading doc `_ for these details. :local: :depth: 2 -.. _CVE-2024-39124: +.. comment: _CVE-2026-csrfL: .. note:: + Releases of Roundup from 2.0.0 to 2.5.0 do not check for cross site + request forgeries (CSRF) when using the ``PATCH`` method. Release + 2.6 fixes this issue. If you are running 2.6.0 you don't have to do + anything. + +.. comment: include:: upgrading.txt + :start-after: .. comment: _CVE-2026-csrfL: + :end-before: .. comment: + +.. comment: _CVE-2026-history_propL: + +.. note:: + + If you are running versions 1.6.0 to version 2.5 the filtering of + history/journal items does not work correctly if the property is + protected by a check function. Release 2.6.0 fixes this. If you are + running 2.6.0, you don't have to do anything. + +.. comment: include:: upgrading.txt + :start-after: .. comment: _CVE-2026-history_prop: + :end-before: .. comment: + +.. comment _CVE-2024-39124L:: + +.. comment note:: + Prior to the release of Roundup 2.4.0, you can access updated tracker templates that address CVE-2024-39124 from `CVE-2024-39124-templates.zip @@ -91,18 +129,18 @@ upgrading doc `_ for these details. file to generate a templates subdirectory containing the classic, minimal and other tracker templates. -.. include:: upgrading.txt - :start-after: .. comment: _CVE-2024-39124: +.. comment include:: upgrading.txt + :start-after: .. _CVE-2024-39124L: :end-before: .. comment: -.. _CVE-2024-39125: +.. comment CVE-2024-39125L: -.. include:: upgrading.txt - :start-after: .. comment: _CVE-2024-39125: +.. comment include:: upgrading.txt + :start-after: .. _CVE-2024-39125L: :end-before: .. comment: -.. _CVE-2024-39126: - -.. include:: upgrading.txt - :start-after: .. comment: _CVE-2024-39126: +.. comment CVE-2024-39126L: + +.. comment include:: upgrading.txt + :start-after: .. _CVE-2024-39126L: :end-before: .. comment: end of CVE include marker diff --git a/doc/Makefile b/doc/Makefile index c4378bb3a..c7b87e9d8 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,8 +1,12 @@ -all: man_html tracker_config.txt admin_help.html - cd ..; ./setup.py build_doc +SPHINX := sphinx-build + +##@ Default target +all: man_html tracker_config.txt admin_help.html ## make all docs under share + cd ..; $(SPHINX) -n -W -b html -d ../build/temp_dir/doc_dir doc share/doc/roundup/html + +##@ build doc parts +tracker_config.txt: ../roundup/configuration.py format_config.awk ## generate a current config file -tracker_config.txt: ../roundup/configuration.py - # generate a current config file python3 ../roundup/scripts/roundup_admin.py \ genconfig _temp_config.txt @@ -15,22 +19,33 @@ tracker_config.txt: ../roundup/configuration.py MAN_ROFF=$(wildcard ../share/man/man1/*.1) MAN_HTML=$(patsubst ../share/man/man1/%.1,html_extra/man_pages/%.1.html,$(MAN_ROFF)) -man_html: $(MAN_HTML) +man_html: $(MAN_HTML) ## generate html versions of man pages for docs html_extra/man_pages/%.1.html: ../share/man/man1/%.1 - man --html=cat $< > $@ - # set max width for paragraphs - sed -i '/ -ROUNDUP-ADMIN +roundup-admin manual page @@ -39,7 +41,7 @@

NAME

-

roundup-admin - +

roundup-admin - administrate roundup trackers

SYNOPSIS @@ -48,7 +50,7 @@

SYNOPSIS -

roundup-admin +

roundup-admin [options] <command> <arguments>

@@ -57,116 +59,125 @@

OPTIONS

-

-i +

-i instance home

-

Specify the issue tracker +

Specify the issue tracker "home directory" to administer

-

-u +

-u user[:password]

-

The user and password to use +

The user and password to use for commands (partial implemention, see Security Notes below).

- + - - + +

Print help text.

+ - + - - + + +

Print full designators (e.g. +issue1) not just id numbers (1).

+ - + - - + + +

When outputting lists of data, +comma-separate them. Same as -S ",".

+

-h

 + -

Print help text.

+
-

-d

 +

-d

 -

Print full designators (e.g. issue1) not just id numbers -(1).

+
-

-c

 +

-c

 -

When outputting lists of data, comma-separate them. Same -as -S ",".

+
-

-S string

+

-S string

-

When outputting lists of data, +

When outputting lists of data, separate items with given string.

- + - - + +as -S " ".

+

-s

 +

When outputting lists of data, space-separate them. Same -as -S " ".

+
-

-P pragma=value

+

-P pragma=value

-

Set a pragma on the command +

Set a pragma on the command line. Multiple -P options can be specified to set multiple pragmas.

- + - - + - - + - - + + - +

-V

 +

Be verbose when importing data.

 +
-

-v

 +

-v

 -

Report Roundup and Python versions and quit.

 +

Report Roundup and Python +versions and quit.
-

Only one of +

Only one of -s, -c or -S can be specified.

COMMANDS @@ -174,209 +185,200 @@

COMMANDS

-

If no command -is provided on the command line, roundup-admin will enter an +

If no command is +provided on the command line, roundup-admin will enter an interactive mode. More details about these commands are available using the help command.

-

A designator is +

A designator is a classname and a nodeid concatenated, eg. bug1, user10, ....

-

Roundup-admin +

Roundup-admin takes a number of commands:

- - + - - + -
+

help

 +

prints help (same as -h)

 +
-

help +

help <subcommand>

-

Print command-specific help

+

Print command-specific help

-

help all

+

help all

-

Print available help for all +

Print available help for all commands.

- - - - - - -
- - -

commit

 +

commit

+

Commit changes made to the +database during an interactive session.

-

Commit changes made to the database during an -interactive session.

- -

The changes +

The changes made during an interactive session are not automatically written to the database - they must be committed using this command.

-

One-off +

One-off commands on the command-line are automatically committed if they are successful. See also rollback.

-

create classname +

create classname property=value ...

-

This creates a new entry of the +

This creates a new entry of the given class using the property name=value arguments provided on the command line after the "create" command.

-

display +

display designator[,designator]*

-

This lists the properties and +

This lists the properties and their associated values for the given node. The pragma display_header can be used to add a header between designators that includes the active/retired status of the item.

-

export +

export [[-]class[,class]] export_dir

-

Export the database to +

Export the database to colon-separated-value files. To exclude the files (e.g. for the msg or file class), use the exporttables command.

-

Optionally +

Optionally limit the export to just the named classes or exclude the named classes, if the 1st argument starts with ’-’.

-

This action +

This action exports the current data from the database into colon-separated-value files that are placed in the nominated destination directory.

-

exporttables +

exporttables [[-]class[,class]] export_dir

-

Export the database to +

Export the database to colon-separated-value files, excluding the files below $TRACKER_HOME/db/files/ (which can be archived separately). To include the files, use the export command.

-

filter classname +

filter classname propname=value ...

-

Find the nodes of the given +

Find the nodes of the given class with a given property value. Multiple values can be specified by separating them with commas. If property is a -string, all values must match. I.E. it’s an matches. -I.E. an ’or’ operation.

+string, all values must match. I.E. it’s an +’and’ operation. If the property is a +link/multilink any value matches. I.E. an ’or’ +operation.

-

find classname +

find classname propname=value ...

-

Find the nodes of the given +

Find the nodes of the given class with a given link property value.

-

genconfig +

genconfig <filename>

-

Generate a new tracker config +

Generate a new tracker config file (ini style) with default values in <filename>. Note that this does not preserve any settings from the current tracker. Use updateconfig for that.

-

get property +

get property designator[,designator]*

-

Get the given property of one +

Get the given property of one or more designator(s).

-

Retrieves the +

Retrieves the property value of the nodes specified by the designators.

-

history designator +

history designator [skipquiet] [raw]

-

Lists the journal entries +

Lists the journal entries viewable by the user for the node identified by the designator. If skipquiet is added, journal entries for quiet properties are not shown. Without the raw option a more human readable output format is used.

-

import +

import import_dir

-

Import a database from the +

Import a database from the directory containing CSV files, two per class to import.

-

The imported +

The imported nodes will have the same nodeid as defined in the import file, thus replacing any existing content.

-

The new nodes +

The new nodes are added to the existing database - if you want to create a new database using the imported data, then create a new database (or, tediously, retire all the old data). See also export.

-

importtables +

importtables import_dir

-

Import a database from the +

Import a database from the directory containing CSV files, two per class to import.

-

The imported +

The imported nodes will have the same nodeid as defined in the import file, thus replacing any existing content.

-

This only +

This only imports database tables. It does not import files/message content. It is used to import data exported by exporttables. See also exporttables.

-

initialise +

initialise [adminpw]

-

Initialise a new Roundup +

Initialise a new Roundup tracker.

-

The +

The administrator details will be set at this step.

-

install [template +

install [template [backend [key=val[,key=val]]]]

-

Install a new roundup +

Install a new roundup tracker.

-

The command +

The command will prompt for the tracker home directory (if not supplied through TRACKER_HOME or the -i option). The template and backend may be specified on the command-line as arguments, in that order.

-

Command line +

Command line arguments following the backend allows you to pass initial values for config options. For example, passing "web_http_auth=no,rdbms_user=dinsdale" will @@ -385,189 +387,189 @@

COMMANDS in this argument! (Enclose whole argument in quotes if you need spaces in option value).

-

The initialise +

The initialise command must be called after this command in order to initialise the tracker’s database. You may edit the tracker’s initial database contents before running that command by editing the tracker’s dbinit.py module init() function.

-

See also +

See also initopts help.

-

list classname +

list classname [property]

-

Lists all instances of the +

Lists all instances of the given class. If the property is not specified, the "label" property is used. The label property is tried in order: the key, "name", "title" and then the first property, alphabetically.

-

With -c, +

With -c, -S or -s print a list of item id’s if no property specified. If property specified, print list of that property for every class instance.

-

The pragma +

The pragma show_retired can be used to print only retired items or to print retired and active items. The default is to print only active items.

-

migrate

+

migrate

-

Update a tracker’s +

Update a tracker’s database to be compatible with the Roundup codebase.

-

You should run +

You should run the "migrate" command for your tracker once you’ve installed the latest codebase.

-

Do this before +

Do this before you use the web, command-line or mail interface and before any users access the tracker.

-

This command +

This command will respond with either "Tracker updated" (if you’ve not previously run it on an RDBMS backend) or "No migration action required" (if you have run it, or have used another interface to the tracker, or possibly because you are using anydbm).

-

It’s safe +

It’s safe to run this even if it’s not required, so just get into the habit.

-

pack period | +

pack period | date

-

Remove journal entries older +

Remove journal entries older than a period of time specified or before a certain date.

-

perftest [mode] +

perftest [mode] [arguments]*

-

Run performance test. For +

Run performance test. For example test the effect of changing password hashing parameters.

-

pragma +

pragma setting=value|list

-

Set internal settings to a +

Set internal settings to a value. E.G.

-

pragma +

pragma verbose=True
pragma verbose=yes
pragma verbose=on
pragma verbose=1

-

will turn on +

will turn on verbose mode for roundup-admin.

-

pragma list

+

pragma list

-

will show all +

will show all settings and their current values. If verbose is enabled hidden settings and descriptions will be shown.

-

reindex +

reindex [classname|classname:#-#|designator]* This will

-

re-generate the search indexes +

re-generate the search indexes for a tracker. You can specify a specific item (or items) (e.g. issue23), range(s) of items (e.g. issue:1-1000), class(es) (e.g. issue) or reindex all items in the database if no arguments are supplied.

-

restore +

restore designator[,designator]*

-

Restore the retired node +

Restore the retired node specified by designator.

-

The given nodes +

The given nodes will become available for users again.

-

retire +

retire designator[,designator]*

-

This action indicates that a +

This action indicates that a particular node is not to be retrieved by the list or find commands, and its key value may be re-used. See also restore.

-

rollback

+

rollback

-

Undo all changes that are +

Undo all changes that are pending commit to the database.

-

The changes +

The changes made during an interactive session are not automatically written to the database - they must be committed manually. This command undoes all those changes, so a commit immediately after would make no changes to the database.

-

security [Role +

security [Role name]

-

Display the Permissions +

Display the Permissions available to one or all Roles.

-

set items +

set items property=value property=value ...

-

Set the given properties of one +

Set the given properties of one or more items(s).

-

The items are +

The items are specified as a class or as a comma-separated list of item designators (ie "designator[,designator,...]").

-

This command +

This command sets the properties to the values for all designators given. If the value is missing (ie. "property=") then the property is un-set. If the property is a multilink, you specify the linked ids for the multilink as comma-separated numbers (ie "1,2,3").

-

specification +

specification classname

-

Show the properties for a +

Show the properties for a classname.

-

templates +

templates [trace_search]]

-

Lists the names, location and +

Lists the names, location and description of all known templates.

-

table classname +

table classname [property[,property]*]

-

Lists all instances of the +

Lists all instances of the given class. If the properties are not specified, all properties are displayed. By default, the column widths are the width of the largest value.

-

The pragma +

The pragma show_retired can be used to print only retired items or to print retired and active items. The default is to print only active items.

-

updateconfig +

updateconfig <filename>

-

This is used when updating +

This is used when updating software. It merges the config.ini from the tracker with new settings from the new software. The merged/updated config file is written to <filename>.

-

Commands may be +

Commands may be abbreviated as long as the abbreviation matches only one command, e.g. l == li == lis == list.

@@ -576,15 +578,15 @@

READLINE SUPPORT

-

You can edit -the command line and interact with history in +

You can edit the +command line and interact with history in roundup-admin’s interactive mode. On Linux like systems, GNU Readline is required. On Mac’s libedit can be used as well. On Windows pyreadline3 is required. See: https://docs.python.org/3/library/readline.html for details on readline.

-

Roundup-admin +

Roundup-admin will save the history between roundup-admin sessions. The commands are saved to the .roundup_admin_history file in the user’s home directory. You can set the pragma @@ -592,17 +594,17 @@

READLINE SUPPORT change the amount of available and stored history for the session.

-

If you are -using GNU readline, you can persistently change the history -size by adding: set history-size 100 to the init file +

If you are using +GNU readline, you can persistently change the history size +by adding: set history-size 100 to the init file .roundup_admin_rlrc located in the user’s home directory.

-

Mac users using +

Mac users using libedit should be able to persistently save history and set the history size by adding history size 100.

-

Users of +

Users of pyreadline3 can use: history_length(100).

SECURITY NOTES @@ -610,14 +612,14 @@

SECURITY NOTES

-

The -u +

The -u user setting does not currently operate like a user logging in via the web. The user running roundup-admin must have read access to the tracker home directory. As a result the user has access to the files and the database info contained in config.ini.

-

Using -u +

Using -u user sets the actor/user parameter in the journal. Changes that are made are attributed to that user. The password is ignored if provided. Any existing username has @@ -632,9 +634,9 @@

ENVIRONMENT VARIABLES -

ROUNDUP_LOGIN

+

ROUNDUP_LOGIN

-

Provides an alternate way to +

Provides an alternate way to set the user.

FURTHER HELP @@ -642,8 +644,8 @@

FURTHER HELP

-

roundup-admin --h
+

roundup-admin -h +
roundup-admin help -- this help
roundup-admin help <command> -- command-specific help
@@ -655,7 +657,7 @@

SEE ALSO -

roundup-demo(1), +

roundup-demo(1), roundup-mailgw(1), roundup-server(1)

AUTHOR @@ -663,11 +665,11 @@

AUTHOR

-

This manpage -was written by Bastian Kleineidam <calvin@debian.org> -for the Debian distribution of roundup.

+

This manpage was +written by Bastian Kleineidam <calvin@debian.org> for +the Debian distribution of roundup.

-

The main author +

The main author of roundup is Richard Jones <richard@users.sourceforge.net>.

diff --git a/doc/html_extra/man_pages/roundup-demo.1.html b/doc/html_extra/man_pages/roundup-demo.1.html index 11bf2ecad..808cde8b9 100644 --- a/doc/html_extra/man_pages/roundup-demo.1.html +++ b/doc/html_extra/man_pages/roundup-demo.1.html @@ -1,19 +1,21 @@ - - + + - + + -ROUNDUP-DEMO +roundup-demo manual page @@ -35,7 +37,7 @@

NAME

-

roundup-demo - +

roundup-demo - create a roundup "demo" tracker and launch its web interface

@@ -45,13 +47,14 @@

SYNOPSIS -

roundup_demo +

roundup_demo [-h] [-b BIND_ADDRESS] [-b {anydbm,mysql,sqlite,postgresql}] -[-t {minimal,jinja2,classic,responsive,devel}] [-p -PORT] [-P URLPORT] [-V] -[directory] [backend] -[nuke]

+[-t +{minimal,jinja2,classic,responsive,devel}] +[-p PORT] [-P URLPORT] +[-V] [directory] [backend] +[nuke]

OPTIONS @@ -59,97 +62,94 @@

OPTIONS -

directory

+

directory

-

The home +

The home directory for the new demo tracker. (*)

-

backend

+

backend

-

Choose backend +

Choose backend database. Depricated, use -b.

- - + - - +
+

nuke

 - - -

Create a fresh demo tracker (deleting the existing one -if any). E.G.

+
-

roundup-demo -b sqlite -t -classic ./mytracker nuke
+

Create a fresh +demo tracker (deleting the existing one if any). E.G.
+roundup-demo -b sqlite -t classic ./mytracker nuke
will remove an existing tracker (if present) from the directory ./mytracker. Then it will create and serve a new empty classic tracker using the sqlite backend.

-

-h, --help

+

-h, --help

-

Show the help +

Show the help message and exit

-

-B BIND_ADDRESS, +

-B BIND_ADDRESS, --bind_address BIND_ADDRESS

-

Choose address +

Choose address for server to listen at. Use 0.0.0.0 to bind to all addreses. Default: 127.0.0.1.

-

-b +

-b {anydbm,mysql,sqlite,postgresql}, --backend_db
{anydbm,mysql,sqlite,postgresql}

-

Choose backend +

Choose backend database. Default: sqlite. Available backends are subject to availability on your system.

-

-t +

-t {minimal,jinja2,classic,responsive,devel}, --template
{minimal,jinja2,classic,responsive,devel}

-

Use specified +

Use specified template when building tracker. (*)

-

-h HOSTNAME, +

-h HOSTNAME, --hostname HOSTNAME

-

Set the +

Set the hostname used in the URL. This does not make the server listen at the hostname. Use the hostname with -B to listen on that IP address.

-

-p PORT, +

-p PORT, --port PORT

-

Listen at this +

Listen at this port. Default: search for open port starting at 8917.

-

-P URLPORT, +

-P URLPORT, --urlport URLPORT

-

When using +

When using docker this option passes the docker external port to the demo instance. If using docker ... -p 9090:8917 ... this should be set to -P 9090. Default: as selected by --port.

-

-V, --version

+

-V, --version

-

Show +

Show program’s version number and exit

-

If items marked +

If items marked with (*) are missing, they will be asked for interactively when setting up the tracker.

@@ -158,7 +158,7 @@

DESCRIPTION

-

This command +

This command creates a fresh demo tracker for you to experiment with. The email features of Roundup will be turned off (so the nosy feature won’t send email). It does this by removing @@ -169,12 +169,12 @@

DESCRIPTION templates directory. The templates command from roundup-admin(1) can help you locate a replacement.

-

If you wish, -you may modify the demo tracker by editing its configuration +

If you wish, you +may modify the demo tracker by editing its configuration files and HTML templates. See the customisation manual for information about how to do that.

-

Once +

Once you’ve fiddled with the demo tracker, you may use it as a template for creating your real, live tracker. Simply run the roundup-admin command to install the tracker @@ -188,7 +188,7 @@

SEE ALSO -

roundup-admin(1), +

roundup-admin(1), roundup-mailgw(1), roundup-server(1)

AUTHOR @@ -196,9 +196,9 @@

AUTHOR

-

This manpage -was written by Richard Jones and extensively modified by -John Rouillard <rouilj@users.sourceforge.net>.

+

This manpage was +written by Richard Jones and extensively modified by John +Rouillard <rouilj@users.sourceforge.net>.

diff --git a/doc/html_extra/man_pages/roundup-mailgw.1.html b/doc/html_extra/man_pages/roundup-mailgw.1.html index 4e763ba81..c32a9eb3e 100644 --- a/doc/html_extra/man_pages/roundup-mailgw.1.html +++ b/doc/html_extra/man_pages/roundup-mailgw.1.html @@ -1,19 +1,21 @@ - - + + - + + -ROUNDUP-MAILGW +roundup-mailgw manual page @@ -37,8 +39,8 @@

NAME

-

roundup-mailgw -- mail gateway for roundup

+

roundup-mailgw - +mail gateway for roundup

SYNOPSIS @@ -46,7 +48,7 @@

SYNOPSIS -

roundup-mailgw +

roundup-mailgw [-h|--help] [-v] [--version] [-c|--default-class default_class] [-S|--set-value [class.]field=value] [-O|--oauth-directory directory] [-T|--oauth-token-endpoint @@ -58,40 +60,40 @@

OPTIONS

-

-v +

-v --version

-

Print version and exit.

+

Print version and exit.

-

-c --default-class +

-c --default-class hyperdb class

-

specify the default tracker +

specify the default tracker class - one of issue (the default), msg, file, user etc. Overrides the tracker’s mailgw default_class setting.

-

-S --set-value +

-S --set-value [class.]property=value[;property=value]

-

specify the values to set on +

specify the values to set on the class specified as prefix using the same format as the Subject line property manipulations. If the class prefix is left out it defaults to msg. Can also be specified with --set-value (and abbreviated to --set).

-

-O --oauth-directory +

-O --oauth-directory directory

-

Only with OAuth authentication +

Only with OAuth authentication specify the directory containing additional OAuth credentials.

-

-T ---oauth-token-endpoint url

+

-T --oauth-token-endpoint +url

-

Token endpoint URL of your +

Token endpoint URL of your cloud provider, only used with OAuth.

DESCRIPTION @@ -99,67 +101,67 @@

DESCRIPTION

-

The roundup -mail gateway may be called in one of four ways:

+

The roundup mail +gateway may be called in one of four ways:

- - + - - + - - + - - + + +

with an instance_home as +the only argument,

- - + - - + + +

with both an +instance_home and a mail spool file, or

- - + - - + + +

with both an instance home and a +mail source type and its specification.

+

•

 +

without arguments which will use the env var ROUNDUP_INSTANCE,

+ -

•

 +

•

 -

with an instance_home as the only argument,

+ -

•

 +

•

 -

with both an instance_home and a mail spool file, -or

+ -

•

 +

•

 -

with both an instance home and a mail source type and -its specification.

-

PIPE -
+

PIPE
If there is no mail source specified, the mail gateway reads a single message from the standard input and submits the message to the roundup.mailgw module.

-

UNIX +

UNIX mailbox
In this case, the gateway reads all messages from the UNIX mail spool file and submits each in turn to the @@ -168,16 +170,16 @@

DESCRIPTION
mailbox /path/to/mailbox

-

In all of the +

In all of the following mail source types, the username and password can -be stored in a ~/.netrc file. If done so, only the server +be stored in a ˜/.netrc file. If done so, only the server name needs to be specified on the command-line.

-

The username +

The username and/or password will be prompted for if not supplied on the -command-line or in ~/.netrc.

+command-line or in ˜/.netrc.

-

POP
+

POP
For the mail source "pop", the gateway reads all messages from the POP server specified and submits each in turn to the roundup.mailgw module. The server is specified @@ -190,19 +192,16 @@

DESCRIPTION pop server
are both valid.

-

POPS -
+

POPS
Connect to the POP server over ssl/tls. This supports the same notation as POP.

-

APOP -
+

APOP
Same as POP, but using Authenticated POP:
apop username:password@server

-

IMAP -
+

IMAP
Connect to an IMAP server. This supports the same notation as that of POP mail.
imap @@ -214,7 +213,7 @@

DESCRIPTION username:password@server mailbox

-

IMAPS +

IMAPS
Connect to an IMAP server over ssl/tls. This supports the same notation as IMAP.
@@ -223,7 +222,7 @@

DESCRIPTION [mailbox]

-

IMAPS_CRAM +

IMAPS_CRAM
Connect to an IMAP server over ssl/tls using CRAM-MD5 authentication. This supports the same notation as IMAP. @@ -233,7 +232,7 @@

DESCRIPTION [mailbox]

-

IMAPS_OAUTH +

IMAPS_OAUTH
Connect to an IMAP server over ssl/tls using OAUTH authentication. Note that this does not support a password @@ -261,7 +260,7 @@

ENVIRONMENT VARIABLES -

ROUNDUP_INSTANCE +

ROUNDUP_INSTANCE
This can be used to set the instance directory. If it is set, the instance_home argument is optional.

@@ -271,17 +270,17 @@

EXAMPLE

-

If your msg +

If your msg class has a messsagetype property you can set up aliases to receive the different types of messages. Setting up an alias in your MTA Using:

-

tracker: +

tracker: |/tools/roundup/bin/roundup-mailgw
-S "msg.messagetype=reply - to all" /var/roundup/sysadmin

-

(the lines are +

(the lines are split for readability. In the alias file they will be on the same line). Replace /tools/roundup/bin/roundup-mailgw by your path to the roundup-mailgw. This creates the email @@ -290,39 +289,39 @@

EXAMPLE all". The roundup tracker instance is located at /var/roundup/sysadmin.

-

A comment alias +

A comment alias would receive emails at tracker_comment with:

-

tracker_comment: +

tracker_comment: |/tools/roundup/bin/roundup-mailgw
-S "msg.messagetype=to tech" /var/roundup/sysadmin

-

which would be -a technical message. These messages can trigger different +

which would be a +technical message. These messages can trigger different workflows based on the messagetype.

-

Both examples +

Both examples use the default class specified in the tracker’s config.ini (usually the issue class).

-

You can also -set properties directly on the issue class. If your +

You can also set +properties directly on the issue class. If your tracker’s issue has a "private" property that limits who can view an issue and its messages:

-

security: +

security: |/tools/roundup/bin/roundup-mailgw
-S "issue.private=true" -S "issue.keyword+=security"
/var/roundup/sysadmin

-

would set the +

would set the private property on a issue to restrict visiblity and mark the issue as a security topic using a keyword.

-

Both examples +

Both examples use the default class specified in the tracker’s config.ini (usually the issue class).

@@ -332,7 +331,7 @@

SEE ALSO -

roundup-admin(1), +

roundup-admin(1), roundup-demo(1), roundup-server(1)

AUTHOR @@ -340,15 +339,15 @@

AUTHOR

-

This manpage -was written by Bastian Kleineidam <calvin@debian.org> -for the Debian distribution of roundup.

+

This manpage was +written by Bastian Kleineidam <calvin@debian.org> for +the Debian distribution of roundup.

-

The main author +

The main author of roundup is Richard Jones <richard@users.sourceforge.net>.

-

Updates by John +

Updates by John Rouillard <rouilj@users.sourceforge.net> and Ralf Schlatterbeck <rsc@runtux.com>.

diff --git a/doc/html_extra/man_pages/roundup-server.1.html b/doc/html_extra/man_pages/roundup-server.1.html index 83373bdfb..ffe4e8a91 100644 --- a/doc/html_extra/man_pages/roundup-server.1.html +++ b/doc/html_extra/man_pages/roundup-server.1.html @@ -1,19 +1,21 @@ - - + + - + + -ROUNDUP-SERVER +roundup-server manual page @@ -36,8 +38,8 @@

NAME

-

roundup-server -- start roundup web server

+

roundup-server - +start roundup web server

SYNOPSIS @@ -45,7 +47,7 @@

SYNOPSIS -

roundup-server +

roundup-server [options] [name=tracker home]*

OPTIONS @@ -53,70 +55,109 @@

OPTIONS

-

-C +

-C file or --config file

-

Use options read from the +

Use options read from the configuration file (see below).

-

-n hostname

+

-n hostname

-

Sets the host name or IP +

Sets the host name or IP address to listen on. Default is localhost (127.0.0.1). Use 0.0.0.0 to listen on all interfaces on the system.

-

-p port

+

-p port

-

Sets the port to listen on +

Sets the port to listen on (default: 8080).

-

-d PIDfile

+

-d PIDfile

-

Run the server in the +

Run the server in the background and write the server’s PID to the file indicated by PIDfile. The -l (or -L) option must be specified if -d is used.

-

-t + + + + + + + +
+ + +

-D

 + + +

Run the server in the foreground even if -d is used.

 +
+ +

-t fork|thread|debug|none

-

Control multi-process mode. +

Control multi-process mode. debug and none are always available. If an invalid mode is specified the server starts in none (also called single) mode. Default fork.

-

-m +

-m max_children

-

Set the maximum number of child +

Set the maximum number of child processes (servers). This value may need to be increased on a heavily loaded site. Default 40.

-

-l file

+

-l file

-

Sets a filename to log to +

Sets a filename to log to (instead of stdout). This is required if the -d option is used.

- + + + + + + - - + + +

Have the server log using the +Python logger with key roundup.http.

+ + +

-P

 + + +

If a reverse proxy is used in front of the +roundup-server, the server will log the ip address of the +proxy, not the client browser. Using -P logs the left most +entry in the X-Forwarded-For http header as the IP address +of the client. This address will be logged or resolved to a +hostname (with -N) and a ’+’ character +will be appended. -P should only be used when the +roundup server is accessible only from trusted proxy hosts. +See: +https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For +for details and warnings about using the X-Forwarded-For +header.

-

-L

 +

-L

 -

Have the server log using the Python logger with key -roundup.http.

-

-i file

+

-i file

-

Sets a filename to use as a +

Sets a filename to use as a template for generating the tracker index page. The variable "trackers" is available to the template and is a dict of all configured trackers. If you connect to the root @@ -124,10 +165,10 @@

OPTIONS page is shown. Using -i allows you to customize the index page.

-

-I +

-I header1[,header2,...]

-

Pass the header(s) and their +

Pass the header(s) and their values to the backend. This allow-list of header variables can be used by custom code in the tracker or with a tracker’s http_auth_header configuration option @@ -137,13 +178,13 @@

OPTIONS - + - - +

-s

 +

Enables use of SSL. In most cases, you will want to run @@ -152,91 +193,73 @@

OPTIONS filter/rate limit/firewall requests to roundup-server.

-

-e file

+

-e file

-

Sets a filename containing the +

Sets a filename containing the PEM file to use for SSL. The PEM file must include both the private key and certificate with appropriate header/trailer markers:

-

-----BEGIN +

-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----

-

and

+

and

-

-----BEGIN +

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

-

If no file is +

If no file is specified, a temporary self-signed certificate will be used.

- + - - + +slower).

+

-N

 +

Log client machine names instead of IP addresses (much -slower).

+
-

-V HTTPVER

+

-V HTTPVER

-

By default roundup-server uses +

By default roundup-server uses HTTP/1.1 to enable keepalives for faster response. HTTPVER can be set to HTTP/1.0 to disable keepalives.

- - - - - - - - - - - - - -
- +

-u UID

-

-u UID

 +

Runs the Roundup web server as +this UID.

+

-g GID

-

Runs the Roundup web server as this UID.

 -
- - -

-g GID

 - - -

Runs the Roundup web server as this GID.

 -
+

Runs the Roundup web server as +this GID.

-

-v or +

-v or --version

-

Print version and exit.

+

Print version and exit.

-

-h or --help

+

-h or --help

-

Print help and exit.

+

Print help and exit.

-

--save-config

+

--save-config

-

Create configuration file and +

Create configuration file and exit. The old config.ini will be saved to config.bak. Note that this command doesn’t attempt to load or verify an existing config.ini. Running this in a tracker home @@ -245,10 +268,10 @@

OPTIONS This will make the tracker in the directory fail to start until the original config.ini is restored.

-

name=tracker +

name=tracker home

-

Sets the tracker home(s) to +

Sets the tracker home(s) to use. The name variable is how the tracker is identified in the URL (it’s the first part of the URL path). The tracker home variable is the directory @@ -260,7 +283,7 @@

OPTIONS characters like spaces, as these confuse the cookie handling in browsers like IE.

-

If you connect +

If you connect to the root directory (I.E. you do not include the name component in the URL, the server will display an index page of trackers served by roundup-server if more than @@ -273,14 +296,14 @@

EXAMPLES -

roundup-server +

roundup-server -p 9000 bugs=/var/tracker reqs=/home/roundup/group1

-

Start the server on port +

Start the server on port 9000 serving two trackers; one under /bugs and one under /reqs.

-

If you connect +

If you connect to the server at the root level (http://host:9000/) it will display a list of the available trackers.

@@ -289,7 +312,7 @@

CONFIGURATION FILE

-

See the +

See the "admin_guide" in the Roundup "doc" directory.

@@ -299,7 +322,7 @@

SEE ALSO -

roundup-admin(1), +

roundup-admin(1), roundup-demo(1), roundup-mailgw(1)

AUTHOR @@ -307,11 +330,11 @@

AUTHOR

-

This manpage -was written by Bastian Kleineidam <calvin@debian.org> -for the Debian distribution of roundup.

+

This manpage was +written by Bastian Kleineidam <calvin@debian.org> for +the Debian distribution of roundup.

-

The main author +

The main author of roundup is Richard Jones <richard@users.sourceforge.net>.

diff --git a/doc/index.txt b/doc/index.txt index 9f1028e16..4b5676e66 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -13,6 +13,7 @@ Contents .. toctree:: :maxdepth: 2 + :includehidden: features @@ -50,6 +51,11 @@ Contents Richard Jones implementation notes security-history +.. toctree:: + :hidden: + + pydoc + See: https://wiki.roundup-tracker.org/ReleaseErrata for fixes to documentation. diff --git a/doc/installation.txt b/doc/installation.txt index bc6f23bf5..a5cd56b41 100644 --- a/doc/installation.txt +++ b/doc/installation.txt @@ -103,12 +103,13 @@ emails. Once you install Roundup, you can use the ``roundup-demo`` command to install new demo trackers. -.. [1] Demo tracker is set up to be accessed by localhost browser. - If you run demo on a server host, please stop the demo (using +.. [1] Demo tracker is set up to be accessed by localhost browser. If + you run demo on a server host, please stop the demo (using Control-C) after it has shown the startup notice, open file - ``demo/config.ini`` with your editor, change host name in - the ``web`` option in section ``[tracker]``, save the file, - then re-run the demo.py program. + ``demo/config.ini`` with your editor, change host name in the + ``web`` option in section ``[tracker]`` from ``localhost`` to + your servers DNS name, save the file, then re-run the demo.py + program. .. _demo mode using docker: @@ -178,7 +179,7 @@ can remove the tracker using ``rm -f`` on the ``demo`` directory. Prerequisites ============= -Roundup requires Python 2.7 [3]_ or 3.6 or newer with a functioning anydbm +Roundup requires Python 3.10 or newer with a functioning anydbm or sqlite module. The version installed by most vendors should work if it meets the version requirements. If necessary, you can download the latest version from https://www.python.org/. It is highly recommended @@ -248,13 +249,23 @@ gpg If gpg_ is installed you can configure the mail gateway to perform verification or decryption of incoming OpenPGP MIME messages. When configured, you can require email to be cryptographically signed - before roundup will allow it to make modifications to issues. + before Roundup will allow it to make modifications to issues. + +nanoid + If nanoid_ is installed, it is used to generate short unique + ids to link all logging to a single request. If not installed, + uuid4's from the standard library are used. jinja2 To use the jinja2 template (may still be experimental, check out its TEMPLATE-INFO.txt file) you need to have the jinja2_ template engine installed. +defusedxml + If you are going to enable and use the XMLRPC endpoint, you should + install the defusedxml_ module. It will still work with the default + xmlrpc standard library, but it will log a warning when used. + .. _install/docutils: docutils @@ -298,6 +309,14 @@ polib roundup-gettext, you must install polib_. See the `developer's guide`_ for details on translating your tracker. +beautifulsoup, justhtml + When HTML only email is received, Roundup can convert it into + plain text using the native dehtml parser. To convert HTML + email into plain text, beautifulsoup4_ or justhtml_ can also be + used. You can choose the converter in the tracker's + config. Note that justhtml is pure Python, fast and conforms to + HTML 5 standards but works only for Python 3.10 or newer. + pywin32 - Windows Service You can run Roundup as a Windows service if pywin32_ is installed. Otherwise it must be started manually. @@ -313,8 +332,8 @@ requests .. _Using Redis for Session Databases: admin_guide.html#using-redis-for-session-databases -.. [3] Do not use Python 2 for new installs. The next minor release - (2.5.0 expected summer 2025) will drop support for Python 2. +.. _gpg install directions in the upgrading document: + upgrading.html#directions-for-installing-gpg Installing Roundup ================== @@ -570,10 +589,7 @@ responsive This issue tracker uses the same schema as devel. The difference between devel and responsive templates is the use of Twitter bootstrap (https://github.com/twbs/bootstrap) in templates and - HTML5 markup. Make sure the "static_files" setting in your - config.ini of your instance is set to the directory where the - static files live (the subdirectory "static" in the default of the - template). + HTML5 markup. jinja2 This is a generic issue tracker based on classic schema. It uses @@ -590,11 +606,14 @@ https://wiki.roundup-tracker.org/TrackerTemplates. Choosing Your Backend --------------------- -The actual storage of Roundup tracker information is handled by backends. +The actual storage of Roundup tracker information is handled by +database backends. Roundup has a process to allow you to change +backends and preserve your tracker's data. So you can upgrade from an +embedded database to MySQL, or PostgreSQL. Roundup supports basic full text search (FTS) for all backends. Some -backends support a faster native FTS. Also Roundup supports using -whoosh or xapian for FTS. +database backends support a faster native FTS. Roundup also supports +using whoosh or xapian for FTS. There are several backends to choose from, each with benefits and limitations: @@ -617,16 +636,11 @@ mysql Fast Many Needs install/admin (MySQLdb_) (e.g. you are interested in adding support for MongoDB or other NoSQL persistence layer). **sqlite** - This uses the embedded database engine SQLite and the PySQLite_ - driver to provide a very fast - backend. This is not suitable for trackers which will have many - simultaneous users, but requires much less installation and maintenance - effort than more scalable postgresql and mysql backends. - - SQLite is supported via PySQLite version 2.1.0 and sqlite3 (the last - being bundled with Python 2.5+) - - Installed SQLite should be the latest version available (3.9.0 or newer). + This uses the SQLite embedded database engine with the sqlite3 + library bundled with Python. This provides a very fast backend. This + is not suitable for trackers which will have many (50+) users + simultaneous updating data. It requires no installation and less + maintenance effort than more scalable postgresql and mysql backends. .. _fts5-testing: @@ -695,8 +709,8 @@ tracker will be heavily used and accessible from the internet, we suggest using Apache or Nginx in WSGI mode or as a reverse proxy to the stand alone web server or WSGI server like Gunicorn. -A FastCGI deployment with an alternate web server is suitable for -lower traffic sites. +A FastCGI or SCGI deployment with an alternate web server is suitable +for lower traffic sites. If you already run Zope, Roundup should deploy nicely in that framework. @@ -708,10 +722,10 @@ Using a true HTTP server provide tools including: DOS prevention, throttling, web application firewalls etc. that are worth having in an internet facing application. -If you are running on an internal intranet, you can use the -stand alone server: roundup-server, but even in this environment, -using a real web server to serve static files and other resources -will perform better. +If you are running on an internal intranet, you can use the stand +alone server: roundup-server, but even in this environment, using a +real web server or proxy (e.g. pound) to serve static files and other +resources will perform better. .. contents:: :depth: 1 @@ -748,7 +762,7 @@ See: https://github.com/MicrosoftDocs/iis-docs/blob/main/iis/web-dev-reference/server-variables.md -More information about ISS setup may be found at: +More information about IIS setup may be found at: https://learn.microsoft.com/en-us/iis/ @@ -1274,18 +1288,94 @@ FastCGI (Cherokee, Hiawatha, lighttpd) The Hiawatha and lighttpd web servers can run Roundup using FastCGI. Cherokee can run FastCGI but it also supports wsgi directly using a -wsgi server like uWSGI, Gnuicorn etc. +wsgi server like Waitress, Gnuicorn etc. To run Roundup using FastCGI, the flup_ package can be used under Python 2 and Python 3. We don't have a detailed config for this, but -the basic idea can be found at: -https://flask.palletsprojects.com/en/2.0.x/deploying/fastcgi/ +the basic idea `can be found in the wayback machine archive`_. If you have deployed Roundup using FastCGI and flup we welcome example configuration files and instructions. +.. _can be found in the wayback machine archive: + https://web.archive.org/web/20241010170738/https://flask.palletsprojects.com/en/2.0.x/deploying/fastcgi/ .. _flup: https://pypi.org/project/flup/ +SCGI (althttpd, Cherokee, lighttpd) +----------------------------------- + +The `althttpd (written by the author of SQLite) +`_ web server is a minimal server that +can run Roundup using SCGI or CGI. + +To run Roundup using SCGI, the flup_ package provides a translator +between SCGI and WSGI. + +The configuration below assumes the web server is running on one host +and the roundup scgi server is running on another host. If they are +both running on the same computer, change ``0.0.0.0`` to ``127.0.0.1`` +and ``hostname`` to ``localhost`` or ``127.0.0.1`` to prevent direct +connection to the roundup scgi server from external hosts. + +The following ``roundup-scgi.py`` can be run using Python to start the +server: + +.. code:: python + + #!/usr/bin/env python + # Obtain the WSGI request dispatcher + from roundup.cgi.wsgi_handler import RequestDispatcher + from flup.server.scgi import WSGIServer + + # Set the path to tracker home. + tracker_home = '/path/to/tracker/home' + + try: + application = RequestDispatcher(tracker_home) + except Exception as e: + print(e) + sys.exit(1) + + ret = WSGIServer(application, + # the tuple: + # hostname/ip address as a string (0.0.0.0 bind + # all ip address) + # port as an integer + bindAddress=("0.0.0.0", 8197), + # Unlike config.ini, the scriptName should + # not end with a /. + scriptName="/roundup.scgi").run() + sys.exit(ret and 42 or 0) + +which is started using ``python roundup-scgi.py``. Note this scgi +configuration serves only one tracker at port 8197. So you run one +scgi server process for each of your trackers. This is different from +cgi, roundup-server or some wsgi deployments where you can access +different trackers through the same entry point. + +Now you have to configure althttpd so it connects to the scgi +server. To do this, althttpd requires a file with a ``.scgi`` +extension. Create the file ``roundup.scgi`` and put it in the root of +your althttpd directory. It should contain: + +.. code:: + + SCGI hostname 8197 + +where hostname is a valid name for the host running the SCGI +server. You can also put in other directives including a fallback web +page if the SCGI server is down, or a command to run to restart the +SCGI server. See the `althttpd.c file +`_ on +the main web site for details. If you have already have althttpd or +althttpsd installed you can just use the ``--help`` argument. + +Assuming you run: +``althttpd --root /var/www/htdocs -port 443 --cert certs.pem`` and you +installed ``/var/www/htdocs/roundup.scgi``, you will be able to access +your tracker at: ``https://web_hostname/roundup.scgi/`` which will +also be the value of your ``web`` setting in the tracker's config.ini. + WSGI Variations --------------- @@ -1432,22 +1522,62 @@ nginx configuration below. If you are customizing a docker continer to use gunicorn, see https://pythonspeed.com/articles/gunicorn-in-docker/. -.. index:: pair: web interface; uWSGI - single: wsgi; uWSGI +.. index:: pair: web interface; Waitress + single: wsgi; Waitress + +Waitress Installation +~~~~~~~~~~~~~~~~~~~~~ + +Waitress is a pure Python WSGI server. It runs on Windows and you +could use IIS or other web server to reverse proxy HTTP to it. + +You can use Waitress to serve Roundup without a proxy. It's not +recommended, but it can be used on a local network where roundup can't +be accessed from the internet. + +Assuming you have installed Roundup in a virtual environment (venv), +install ``waitress`` and ``paste`` into the same venv using +pip. ``paste`` is optional, but it provides logging middleware that +produces standard combined format HTTP connection logs. You need to +modify the file wsgi.py (obtained from ``frontends/wsgi.py``) to +invoke waitress. It will look like:: + + # If you installed roundup to the system locations + # using pip you don't need to change this + # section. If you installed roundup in a custom + # location, uncomment these lines and change the + # path in the append() method to your custom path. + #import sys + #sys.path.append('/custom/location/where/roundup/is/installed') + + # Obtain the WSGI request dispatcher + from roundup.cgi.wsgi_handler import RequestDispatcher + + # Set the path to tracker home. + tracker_home = 'demo' -uWSGI Installation -~~~~~~~~~~~~~~~~~~ + # Definition signature for app: app(environ, start_response): + # If using apache mod_wsgi change app to application. + app = RequestDispatcher(tracker_home) -For a basic roundup install using uWSGI behind a front end server, -install uwsgi and the python3 (or python) plugin. Then run:: + from waitress import serve + # Optional replaced TransLogger(app) with app if not installed + from paste.translogger import TransLogger + serve(TransLogger(app), + host='0.0.0.0', + port=8917, + url_prefix=f"/{tracker_home}/") - uwsgi --http-socket 127.0.0.1:8917 \ - --plugin python3 --mount=/tracker=wsgi.py \ - --manage-script-name --callable app +This will make Roundup available to any host on your local network at +port 8917 under the ``/demo/`` path. Run it with ``python wsgi.py``. +If you want to run just on the local loopback interface, replace +``0.0.0.0`` with ``127.0.0.1`` -using the same wsgi.py as was used for Gunicorn. If you get path not -found errors, check the mount option. The /tracker entry must match -the path used for the [tracker] web value in the tracker's config.ini. +`See the Waitress docs`_ for more info on configuring waitress +including putting it behind a proxy, IPV6 support etc. + +.. _`See the Waitress docs`: + https://docs.pylonsproject.org/projects/waitress/en/stable/ Configure an Email Interface ============================ @@ -2308,32 +2438,29 @@ Make sure you read the instructions under `UNIX environment steps`_. Problems? Testing your Python... ================================ -.. note:: - The ``run_tests.py`` script is not packaged in Roundup's source - distribution anymore. You should install: - - * pytest, - * requests, and - * mock - - using your distributions package manger or using pip/pip2/pip3 to - install pytest etc. for your Python version. See the - `administration guide`_ for details. - - Remember to have a database user 'rounduptest' prepared (with - password 'rounduptest'). This user - must have at least the rights to create and drop databases. - Documentation: details on `adding MySQL users`_, - for PostgreSQL you want to call the ``createuser`` command with the - ``-d`` option to allow database creation. - -This can only be done if you `install the source`_ distribution -(steps 1-3) or from a `mercurial checkout -<../code.html#get-sources>`_. It will not work if you used `pip -install` as the test suite is not installed. Once you've unpacked -roundup's source, if you have pytest installed, run ``python -m -pytest test`` in the Roundup source directory and make sure there -are no errors. If there are errors, please let us know! +This can only be done if you `install the source`_ distribution (steps +1-3) or from a `mercurial checkout <../code.html#get-sources>`_. It +will not work if you used `pip install` as the test suite is not +installed. Once you've unpacked roundup's source, you need to install +the testing requirements. You probably want to do this in an activated +virtual environment. This can be done with:: + + python -m pip install -r test/requirements.txt + +or you can install all the packages listed in requirements.txt using +your distribution's package manager. + +If you are testing postgresql or mysql/mariadb you must have a +database user 'rounduptest' (with password 'rounduptest'). This user +must have at least the rights to create and drop databases. +Documentation: details on `adding MySQL users`_, for PostgreSQL you +want to call the ``createuser`` command with the ``-d`` option to +allow database creation. The test suite will skip tests where the +database driver software is missing. + +Then run ``python -m pytest test`` in the Roundup source directory and +make sure there are no errors. If there are errors, please let us +know! Note that redis tests uses database 15 of the redis server running on localhost.The tests verify that the database is empty before the redis @@ -2369,18 +2496,22 @@ the test. .. _`adding MySQL users`: https://dev.mysql.com/doc/refman/8.0/en/creating-accounts.html .. _apache: https://httpd.apache.org/ +.. _beautifulsoup4: https://pypi.org/project/beautifulsoup4/ .. _brotli: https://pypi.org/project/Brotli/ .. _`developer's guide`: developers.html +.. _defusedxml: https://pypi.org/project/defusedxml/ .. _docutils: https://pypi.org/project/docutils/ .. _flup: https://pypi.org/project/flup/ .. _gpg: https://www.gnupg.org/software/gpgme/index.html .. _jinja2: https://palletsprojects.com/projects/jinja/ +.. _justhtml: https://pypi.org/project/justhtml/ .. _markdown: https://python-markdown.github.io/ .. _markdown2: https://github.com/trentm/python-markdown2 .. _mistune: https://pypi.org/project/mistune/ .. _mod_python: https://github.com/grisha/mod_python .. _mod_wsgi: https://pypi.org/project/mod-wsgi/ .. _MySQLdb: https://pypi.org/project/mysqlclient/ +.. _nanoid: https://pypi.org/project/nanoid/ .. _Olson tz database: https://www.iana.org/time-zones .. _polib: https://polib.readthedocs.io .. _Psycopg2: https://www.psycopg.org/ diff --git a/doc/mysql.txt b/doc/mysql.txt index 71edee8c2..b07b0f035 100644 --- a/doc/mysql.txt +++ b/doc/mysql.txt @@ -13,11 +13,8 @@ Prerequisites To use MySQL as the backend for storing roundup data, you also need to install: -1. MySQL RDBMS 4.0.18 or higher - https://www.mysql.com/. Your MySQL - installation MUST support InnoDB tables (or Berkeley DB (BDB) tables - if you have no other choice). If you're running < 4.0.18 (but not <4.0) - then you'll need to use BDB to pass all unit tests. Edit the - ``roundup/backends/back_mysql.py`` file to enable DBD instead of InnoDB. +1. MySQL RDBMS 8.0.11 or higher - https://www.mysql.com/. Your MySQL + installation MUST support InnoDB tables. 2. Python MySQL interface - https://pypi.org/project/mysqlclient/ diff --git a/doc/pydoc.txt b/doc/pydoc.txt new file mode 100644 index 000000000..36df7250f --- /dev/null +++ b/doc/pydoc.txt @@ -0,0 +1,54 @@ +================================ +Embedded documentation from code +================================ + +.. contents:: + :local: + +The following are embedded documentation selected from the Roundup +code base. You can see the same information using the ``help`` +function after importing the modules. + +Client class +============ + +.. autoclass:: roundup.cgi.client::Client + :members: + +CGI Action class +================ + +Action class and selected derived classes. + +Action +------ +.. autoclass:: roundup.cgi.actions::Action + :members: + +LoginAction +------------ + +.. autoclass:: roundup.cgi.actions::LoginAction + :members: + +.. _`ReauthAction_pydoc`: + +ReauthAction +------------ + +.. autoclass:: roundup.cgi.actions::ReauthAction + :members: + +Templating Utils class +====================== + +.. autoclass:: roundup.cgi.templating::TemplatingUtils + :members: + +Logcontext Module +================= +.. _logcontext_pydoc: + +.. automodule:: roundup.logcontext + :members: + :exclude-members: SimpleSentinel diff --git a/doc/reference.txt b/doc/reference.txt index 23f2b65d8..3dea2518a 100644 --- a/doc/reference.txt +++ b/doc/reference.txt @@ -442,25 +442,16 @@ Properties A Class consists of one or more properties of the following types: -String - properties store arbitrary-length strings. -Password - properties store encoded arbitrary-length strings. - The default encoding is defined in the ``roundup.password.Password`` - class. +Boolean + properties store on/off, yes/no, true/false values. Date properties store date-and-time stamps. Their values are Timestamp objects. +Integer + properties store integer values. (Number can store real/float values.) Interval properties store time periods rather than absolute dates. For example 2 hours. -Integer - properties store integer values. (Number can store real/float values.) -Number - properties store numeric values. There is an option to use - double-precision floating point numbers. -Boolean - properties store on/off, yes/no, true/false values. Link properties refers to a single item selected from a specified class. The class is part of the property; the value is an @@ -468,6 +459,15 @@ Link Multilink properties refer to one or more items in a specified class. The value is a list of integers. +Number + properties store numeric values. There is an option to use + double-precision floating point numbers. +Password + properties store encoded arbitrary-length strings. + The default encoding is defined in the ``roundup.password.Password`` + class. +String + properties store arbitrary-length strings. Properties have attributes to change the default behaviour: @@ -481,8 +481,8 @@ Properties have attributes to change the default behaviour: the list returned by calling get_required_props for the class. - ``default_value``: see `design documentation`_ Sets the default value if the property is not set. - - ``quiet``: see `design documentation`_. Suppresses user visible - to changes to this property. The property change is not reported: + - ``quiet``: see `design documentation`_. Suppresses reporting user + visible changes to this property. The property change is not reported: - in the change feedback/confirmation message in the web interface @@ -744,6 +744,11 @@ create(information) Create an item in the database. This is used to create items in the :term:`definitional class` like "priority" and "status". +.. index:: triple: schema; class property; messages + triple: schema; class property; files + triple: schema; class property; nosy + triple: schema; class property; superseder + IssueClass ~~~~~~~~~~ @@ -756,6 +761,8 @@ users to tell about changes to the issue. They get "CC'ed" e-mails when messages are sent to or generated by the issue. The nosy reactor (in the ``'detectors'`` directory) handles this action. The superseder link indicates an issue which has superseded this one. +It is better described in the +`original document `_. They also have the default "creation", "activity" and "creator" properties. @@ -855,11 +862,6 @@ file class allows for other possibilities including: done on the filesystem outside of the Roundup mechanism. * keeping multiple revisions of the file. -.. index:: triple: schema; class property; messages - triple: schema; class property; files - triple: schema; class property; nosy - triple: schema; class property; superseder - .. index:: schema; item ordering A note about ordering @@ -886,7 +888,7 @@ Examples of adding to your schema See :ref:`CustomExamples` for examples. -The Roundup wiki CategorySchema`_ provides a list of additional +The `Roundup wiki CategorySchema`_ provides a list of additional examples of how to customize schemas to add new functionality. .. _Roundup wiki CategorySchema: @@ -946,11 +948,36 @@ directory. You are free to add and remove them any time, even after the database is initialised via the ``roundup-admin initialise`` command. -Detectors in your tracker are run *before* (**auditors**) and *after* -(**reactors**) changes to the contents of your database. You will have -some installed by default - have a look. You can write new detectors -or modify the existing ones. The existing detectors installed for you -are: +There are two types of detectors: + + 1. *auditors* are run before changes are made to the database + 2. *reactors* are run after the change has been committed to the database + +.. index:: auditors; rules for use + single: reactors; rules for use + +Auditor or Reactor? +------------------- + +Generally speaking, you should observe the following rules: + +**Auditors** + Are used for `vetoing creation of or changes to items`_. They might + also make automatic changes to item properties. They can raise the + ``Reject`` or ``CheckId`` exceptions to control database changes. +**Reactors** + Detect changes in the database and react accordingly. They should avoid + making changes to the database where possible, as this could create + detector loops. + + +Detectors Installed by Default +------------------------------ + +You will have some detectors installed by default - have a look in the +``detectors`` subdirectory of your tracker home. You can write new +detectors or modify the existing ones. The existing detectors +installed for you are: .. index:: detectors; installed @@ -960,6 +987,13 @@ are: to issues. The nosy auditor (``updatenosy``) fires when issues are changed, and figures out what changes need to be made to the nosy list (such as adding new authors, etc.) + + If you are running a tracker started with ``roundup-demo`` or the + ``demo.py`` script, this detector will be missing.This is + intentional to prevent email from being sent from a demo + tracker. You can find the nosyreaction.py detector in the + :term:`template directory (meaning 3)